root
/
spring-boot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

Merge pull request #11489 from Buzzardo:linking

Browse Source 
* pr/11489:
  Polish
  Full editing pass plus linking
pull/11502/head
Brian Clozel 7 years ago
parent 0aedd3f11d c6a1fc93bd
commit b96f862c9e
9 changed files with 1133 additions and 1005 deletions
Show Stats Download Patch File Download Diff File

21
spring-boot-project/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc
Unescape Escape View File

@ -67,8 +67,9 @@ as the original jar in the `target` directory:
----
If you do not include the `<execution/>` configuration as shown in the prior example, you
can run the plugin on its own (but only if the package goal is used as well). For example:
If you do not include the `<execution/>` configuration, as shown in the prior example, you
can run the plugin on its own (but only if the package goal is used as well), as shown in
the following example:
[indent=0]
----
@ -78,7 +79,7 @@ can run the plugin on its own (but only if the package goal is used as well). Fo
----
If you use a milestone or snapshot release, you also need to add the appropriate
`pluginRepository` elements as shown in the following listing:
`pluginRepository` elements, as shown in the following listing:
[source,xml,indent=0,subs="verbatim,attributes"]
----
@ -115,7 +116,7 @@ the usual `packaging` element, as shown in the following example:
----
Your existing archive is enhanced by Spring Boot during the `package` phase. The main
class that you want to launch can either be specified by using a configuration option or
class that you want to launch can be specified either by using a configuration option or
by adding a `Main-Class` attribute to the manifest in the usual way. If you do not specify
a main class, the plugin searches for a class with a
`public static void main(String[] args)` method.
@ -229,7 +230,7 @@ attributes are supported by the task:
|`start-class`
|The main application class to run
|No _(default is first class found declaring a `main` method)_
|No _(the default is the first class found that declares a `main` method)_
|====
The following nested elements can be used with the task:
@ -252,6 +253,9 @@ of the application.
==== Examples
This section shows two examples of Ant tasks.
.Specify +start-class+
[source,xml,indent=0]
----
@ -280,7 +284,7 @@ of the application.
[[spring-boot-ant-findmainclass]]
=== `spring-boot:findmainclass`
The `findmainclass` task is used internally by `exejar` to locate a class declaring a
`main`. You can also use this task directly in your build, if needed. The following
`main`. If necessary, you can also use this task directly in your build. The following
attributes are supported:
[cols="1,2,2"]
@ -303,6 +307,9 @@ attributes are supported:
==== Examples
This section contains three examples of using `findmainclass`.
.Find and log
[source,xml,indent=0]
----
@ -367,7 +374,7 @@ candidate is found.
[[build-tool-plugins-repackage-implementation]]
=== Example Repackage Implementation
The following listing shows a typical example repackage:
The following example shows a typical repackage implementation:
[source,java,indent=0]
----

64
spring-boot-project/spring-boot-docs/src/main/asciidoc/deployment.adoc
Unescape Escape View File

@ -17,16 +17,16 @@ This section covers some of the more common deployment scenarios.
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`". They manage application processes (not Java applications
specifically), so they need some intermediary layer that adapts _your_ application to the
specifically), so they need an intermediary layer that adapts _your_ application to the
_cloud's_ notion of a running process.
Two popular cloud providers, Heroku and Cloud Foundry, employ a "`buildpack`" approach.
The buildpack wraps your deployed code in whatever is needed to _start_ your application:
it might be a JDK and a call to `java`, it might be an embedded web server, or it might be
a full-fledged application server. A buildpack is pluggable, but ideally you should be
able to get by with as few customizations to it as possible. This reduces the footprint of
functionality that is not under your control. It minimizes divergence between development
and production environments.
The buildpack wraps your deployed code in whatever is needed to _start_ your application.
It might be a JDK and a call to `java`, an embedded web server, or a full-fledged
application server. A buildpack is pluggable, but ideally you should be able to get by
with as few customizations to it as possible. This reduces the footprint of functionality
that is not under your control. 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.
@ -148,7 +148,7 @@ extracts them and flattens the data into properties that can be accessed through
All Cloud Foundry properties are prefixed with `vcap`. You can use `vcap` properties to
access application information (such as the public URL of the application) and service
information (such as database credentials). See
information (such as database credentials). See the
{dc-spring-boot}/cloud/CloudFoundryVcapEnvironmentPostProcessor.html['`CloudFoundryVcapEnvironmentPostProcessor`']
Javadoc for complete details.
@ -175,7 +175,7 @@ shows the `Procfile` for our starter REST application:
Spring Boot makes `-D` arguments available as properties accessible from a Spring
`Environment` instance. The `server.port` configuration property is fed to the embedded
Tomcat, Jetty, or Undertow instance which, then uses the port when it starts up. The `$PORT`
Tomcat, Jetty, or Undertow instance, which then uses the port when it starts up. The `$PORT`
environment variable is assigned to us by the Heroku PaaS.
This should be everything you need. The most common deployment workflow for Heroku
@ -234,8 +234,7 @@ https://www.openshift.com/[OpenShift] is the Red Hat public (and enterprise) ext
the Kubernetes container orchestration platform. Similarly to Kubernetes, OpenShift has
many options for installing Spring Boot based applications.
OpenShift has many resources describing how to deploy Spring Boot applications, which
include:
OpenShift has many resources describing how to deploy Spring Boot applications, including:
* https://blog.openshift.com/using-openshift-enterprise-grade-spring-boot-deployments/[Using the S2I builder]
* https://access.redhat.com/documentation/en-us/reference_architectures/2017/html-single/spring_boot_microservices_on_red_hat_openshift_container_platform_3/[Architecture guide]
@ -255,7 +254,7 @@ server. The options include:
* AWS Cloud Formation
* AWS Container Registry
Each has different features and pricing model. In this document, we describe only the
Each has different features and pricing models. In this document, we describe only the
simplest option: AWS Elastic Beanstalk.
@ -269,8 +268,8 @@ either use the "`Tomcat Platform`" or the "`Java SE platform`".
===== Using the Tomcat Platform
This option applies to Spring Boot projects that produce a war file. There is no any
special configuration required. You need only follow the official guide.
This option applies to Spring Boot projects that produce a war file. No
special configuration is required. You need only follow the official guide.
@ -290,7 +289,7 @@ your `application.properties` file:
.Upload binaries instead of sources
====
By default, Elastic Beanstalk uploads sources and compiles them in AWS. However, it is
best to upload the binaries instead. To do so, add the following lines to your
best to upload the binaries instead. To do so, add lines similar to the following to your
`.elasticbeanstalk/config.yml` file:
@ -355,11 +354,11 @@ more options. If there is a https://boxfuse.com/docs/commandline/#configuration
TIP: By default, Boxfuse activates a Spring profile named `boxfuse` on startup. If your
executable jar or war contains an
https://boxfuse.com/docs/payloads/springboot.html#configuration
[`application-boxfuse.properties`] file, Boxfuse bases its configuration based on the
[`application-boxfuse.properties`] file, Boxfuse bases its configuration on the
properties it contains.
At this point, `boxfuse` creates an image for your application, uploads it, and configures
and starts the necessary resources on AWS resulting in output similar to the following
and starts the necessary resources on AWS, resulting in output similar to the following
example:
[indent=0,subs="verbatim,quotes,attributes"]
@ -405,7 +404,7 @@ it empty and then use the https://cloud.google.com/sdk/downloads[Google Cloud SD
push your Spring Boot app into that slot from the command line or CI build.
App Engine needs you to create an `app.yaml` file to describe the resources your app
requires. Normally you put this file in `src/main/appengine`, and it should resemble the
requires. Normally, you put this file in `src/main/appengine`, and it should resemble the
following file:
[source,yaml,indent=0]
@ -464,11 +463,11 @@ can be executed like any other executable binary or it can be
<<deployment-service,registered with `init.d` or `systemd`>>. This makes it very easy to
install and manage Spring Boot applications in common production environments.
WARNING: Fully executable jars work by embedding an extra script at the front of the file.
CAUTION: Fully executable jars work by embedding an extra script at the front of the file.
Currently, some tools do not accept this format, so you may not always be able to use this
technique. For example, `jar -xf` may silently fail to extract a jar or war that has been
made fully executable. It is recommended that you only make your jar or war fully
executable if you intend to execute it directly, rather than running it with `java -jar`
made fully executable. It is recommended that you make your jar or war fully executable
only if you intend to execute it directly, rather than running it with `java -jar`
or deploying it to a servlet container.
To create a '`fully executable`' jar with Maven, use the following plugin configuration:
@ -516,7 +515,7 @@ Spring Boot application can be easily started as Unix/Linux services by using ei
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. To do so, symlink the jar to `init.d` to
support the standard `start`, `stop`, `restart` and `status` commands.
support the standard `start`, `stop`, `restart`, and `status` commands.
The script supports the following features:
@ -533,7 +532,7 @@ Spring Boot application as an `init.d` service, create a symlink, as follows:
----
Once installed, you can start and stop the service in the usual way. For example, on a
Debian based system, you could start it with the following command:
Debian-based system, you could start it with the following command:
[indent=0,subs="verbatim,quotes,attributes"]
----
@ -638,7 +637,7 @@ place it in `/etc/systemd/system` directory. The following script offers an exam
WantedBy=multi-user.target
----
IMPORTANT: Remember to change the `Description`, `User` and `ExecStart` fields for your
IMPORTANT: Remember to change the `Description`, `User`, and `ExecStart` fields for your
application.
NOTE: The `ExecStart` field does not declare the script action command, which means that
@ -666,7 +665,7 @@ Refer to `man systemctl` for more details.
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. If you find you cannot customize something that you need
to, you can always use the `embeddedLaunchScript` option to write your own file entirely.
to, use the `embeddedLaunchScript` option to write your own file entirely.
@ -785,8 +784,8 @@ The following environment properties are supported with the default script:
|The name of the log file in the `LOG_FOLDER` (`<appname>.log` by default).
|`APP_NAME`
|The name of the app. If the jar is run from a symlink, the script guesses the app name if
it is not a symlink or you want to explicitly set the app name, this can be useful.
|The name of the app. If the jar is run from a symlink, the script guesses the app name.
If it is not a symlink or you want to explicitly set the app name, this can be useful.
|`RUN_ARGS`
|The arguments to pass to the program (the Spring Boot app).
@ -818,10 +817,11 @@ http://www.freedesktop.org/software/systemd/man/systemd.service.html[service uni
configuration man page] for more details.
[[deployment-script-customization-conf-file]]
With the exception of `JARFILE` and `APP_NAME`, the above settings can be configured by
using a `.conf` file. The file is expected to be next to the jar file and have the same
name but suffixed with `.conf` rather than `.jar`. For example, a jar named
`/var/myapp/myapp.jar` uses the configuration file named `/var/myapp/myapp.conf`.
With the exception of `JARFILE` and `APP_NAME`, the settings listed in the preceding
section can be configured by using a `.conf` file. The file is expected to be next to the
jar file and have the same name but suffixed with `.conf` rather than `.jar`. For example,
a jar named `/var/myapp/myapp.jar` uses the configuration file named
`/var/myapp/myapp.conf`, as shown in the following example:
.myapp.conf
[indent=0,subs="verbatim,quotes,attributes"]
@ -842,7 +842,7 @@ To learn about securing this file appropriately, see
A Spring Boot application can be started as a Windows service by using
https://github.com/kohsuke/winsw[`winsw`].
A sample (https://github.com/snicoll-scratches/spring-boot-daemon[maintained separately])
A (https://github.com/snicoll-scratches/spring-boot-daemon[separately maintained sample])
describes step-by-step how you can create a Windows service for your Spring Boot
application.

44
spring-boot-project/spring-boot-docs/src/main/asciidoc/getting-started.adoc
Unescape Escape View File

@ -3,7 +3,7 @@
[partintro]
--
If you are getting started with Spring Boot, or "Spring" in general, start by reading
If you are getting started with Spring Boot, or "`Spring`" in general, start by reading
this section. It answers the basic "`what?`", "`how?`" and "`why?`" questions. It
includes an introduction to Spring Boot, along with installation instructions. We then
walk you through building your first Spring Boot application, discussing some core
@ -14,7 +14,7 @@ principles as we go.
[[getting-started-introducing-spring-boot]]
== Introducing Spring Boot
Spring Boot makes it easy to create stand-alone, production-grade Spring based
Spring Boot makes it easy 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. Most Spring Boot
applications need very little Spring configuration.
@ -25,7 +25,7 @@ runs "`spring scripts`".
Our primary goals are:
* Provide a radically faster and widely accessible getting started experience for all
* Provide a radically faster and widely accessible getting-started experience for all
Spring development.
* Be opinionated out of the box but get out of the way quickly as requirements start to
diverge from the defaults.
@ -38,15 +38,15 @@ configuration).
[[getting-started-system-requirements]]
== System Requirements
Spring Boot {spring-boot-version} requires http://www.java.com[Java 8] and Spring
Framework {spring-version} or above. Explicit build support is provided for Maven 3.2+
and Gradle 4.
Spring Boot {spring-boot-version} requires http://www.java.com[Java 8] and
{spring-reference}[Spring Framework {spring-version}] or above. Explicit build support is
provided for Maven 3.2+ and Gradle 4.
[[getting-started-system-requirements-servlet-containers]]
=== Servlet Containers
The following embedded servlet containers are supported out of the box:
Spring Boot supports the following embedded servlet containers:
|===
|Name |Servlet Version
@ -78,7 +78,7 @@ begin, you should check your current Java installation by using the following co
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, otherwise, read on for "`classic`" installation instructions.
Line Interface) first. Otherwise, read on for "`classic`" installation instructions.
@ -102,8 +102,8 @@ Maven installed, you can follow the instructions at http://maven.apache.org.
TIP: On many operating systems, Maven can be installed with a package manager. If you use
OSX Homebrew, try `brew install maven`. Ubuntu users can run
`sudo apt-get install maven`. Windows users with Chocolatey can run `choco install maven`
from an elevated (administrator) prompt.
`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
@ -298,7 +298,7 @@ commands:
Spring Boot v{spring-boot-version}
----
If you are developing features for the CLI and want easy access to the version you built,
If you develop features for the CLI and want easy access to the version you built,
use the following commands:
[indent=0,subs="verbatim,quotes,attributes"]
@ -372,8 +372,8 @@ http://en.wikipedia.org/wiki/Zsh[zsh] shells. You can `source` the script (also
`spring`) in any shell or put it in your personal or system-wide bash completion
initialization. On a Debian system, the system-wide scripts are in
`/shell-completion/bash` and all scripts in that directory are executed when a new shell
starts. For example, to run the script manually if you have installed using SDKMAN!, use
the following commands:
starts. For example, to run the script manually if you have installed by using SDKMAN!,
use the following commands:
[indent=0]
----
@ -415,7 +415,7 @@ Then run it from a shell, as follows:
NOTE: The first run of your application is slow, as dependencies are downloaded.
Subsequent runs are much quicker.
Open http://localhost:8080 in your favorite web browser. You should see the following
Open `http://localhost:8080` in your favorite web browser. You should see the following
output:
[indent=0]
@ -427,13 +427,13 @@ output:
[[getting-started-upgrading-from-an-earlier-version]]
=== Upgrading from an Earlier Version of Spring Boot
If you are upgrading from an earlier release of Spring Boot check the "`release notes`"
hosted on the {github-wiki}[project wiki]. You'll find upgrade instructions along with a
If you are upgrading from an earlier release of Spring Boot, check the "`release notes`"
hosted on the {github-wiki}[project wiki]. You can find upgrade instructions along with a
list of "`new and noteworthy`" features for each release.
To upgrade an existing CLI installation use the appropriate package manager command (for
To upgrade an existing CLI installation, use the appropriate package manager command (for
example, `brew upgrade`) or, if you manually installed the CLI, follow the
<<getting-started-manual-cli-installation, standard instructions>> remembering to update
<<getting-started-manual-cli-installation, standard instructions>>, remembering to update
your `PATH` environment variable to remove any older references.
@ -477,7 +477,7 @@ valid versions of Java and Maven installed:
----
NOTE: This sample needs to be created in its own folder. Subsequent instructions assume
that you have created a suitable folder and that it is your "`current directory`".
that you have created a suitable folder and that it is your current directory.
@ -646,7 +646,7 @@ accordingly.
****
Auto-configuration is designed to work well with "`Starters`", but the two concepts are
not directly tied. You are free to pick and choose jar dependencies outside of the
starters and Spring Boot still does its best to auto-configure your application.
starters. Spring Boot still does its best to auto-configure your application.
****
@ -687,7 +687,7 @@ application. You should see output similar to the following:
........ Started Example in 2.222 seconds (JVM running for 6.514)
----
If you open a web browser to http://localhost:8080, you should see the following output:
If you open a web browser to `http://localhost:8080`, you should see the following output:
[indent=0]
----
@ -718,7 +718,7 @@ can also be problematic if the same filename is used (but with different content
multiple jars.
Spring Boot takes a <<appendix-executable-jar-format.adoc#executable-jar, different
approach>> and allows you to actually nest jars directly.
approach>> and lets you actually nest jars directly.
****
To create an executable jar, we need to add the `spring-boot-maven-plugin` to our

691
spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc
View File

File diff suppressed because it is too large Load Diff

8
spring-boot-project/spring-boot-docs/src/main/asciidoc/index.adoc
Unescape Escape View File

@ -39,6 +39,12 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
:spring-boot-maven-plugin-site: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/maven-plugin/
:spring-boot-gradle-plugin: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/gradle-plugin/
:spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/
:spring-rest-docs: http://projects.spring.io/spring-restdocs/
:spring-integration: http://projects.spring.io/spring-integration/
:spring-session: https://projects.spring.io/spring-session/
:spring-framework: http://projects.spring.io/spring-framework/
:spring-security: http://projects.spring.io/spring-security/
:spring-data-jpa: http://projects.spring.io/spring-data-jpa/
:spring-security-reference: http://docs.spring.io/spring-security/site/docs/{spring-security-docs-version}/reference/htmlsingle
:spring-security-oauth2-reference: http://projects.spring.io/spring-security-oauth/docs/oauth2.html
:spring-webservices-reference: http://docs.spring.io/spring-ws/docs/{spring-webservices-docs-version}/reference/
@ -48,6 +54,8 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
:spring-data-javadoc: http://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa
:spring-data-commons-javadoc: http://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data
:spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb
:spring-data-mongo: http://projects.spring.io/spring-data-mongodb/
:spring-data: http://projects.spring.io/spring-data/
:spring-data-rest-javadoc: http://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest
:gradle-userguide: http://www.gradle.org/docs/current/userguide
:propdeps-plugin: https://github.com/spring-projects/gradle-plugins/tree/master/propdeps-plugin

240
spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc
Unescape Escape View File

@ -19,7 +19,7 @@ features is to add a dependency to the `spring-boot-starter-actuator` '`Starter`
.Definition of Actuator
****
An actuator is a manufacturing term, referring to a mechanical device for moving or
An actuator is a manufacturing term that refers to a mechanical device for moving or
controlling something. Actuators can generate a large amount of motion from a small
change.
****
@ -71,8 +71,8 @@ The following technology-agnostic endpoints are available:
|Displays a complete list of all the Spring beans in your application.
|`conditions`
|Showing the conditions that were evaluated on configuration and auto-configuration
classes and the reasons why they did or did not match.
|Shows the conditions that were evaluated on configuration and auto-configuration
classes and the reasons why they did or did not match.
|`configprops`
|Displays a collated list of all `@ConfigurationProperties`.
@ -106,7 +106,7 @@ The following technology-agnostic endpoints are available:
|`sessions`
|Allows retrieval and deletion of user sessions from a Spring Session-backed session
store. Not available when using Spring Session's support for reactive web applications.
store. Not available when using Spring Session's support for reactive web applications.
|`shutdown`
|Lets the application be gracefully shutdown (not enabled by default).
@ -139,21 +139,20 @@ content.
|===
To learn more about the Actuator's endpoints and their request and response formats,
please refer to the separate API documentation that is available in the following formats:
* {spring-boot-actuator-api}/html[HTML]
* {spring-boot-actuator-api}/pdf/spring-boot-actuator-web-api.pdf[PDF]
please refer to the separate API documentation ({spring-boot-actuator-api}/html[HTML] or
{spring-boot-actuator-api}/pdf/spring-boot-actuator-web-api.pdf[PDF]).
[[production-ready-endpoints-exposing-endpoints]]
=== Exposing Endpoints
Since Endpoints may contain sensitive information, careful consideration should be given
about when to expose them. Out of the box, Spring Boot will expose all enabled endpoints
over JMX, but only the `health` and `info` endpoints over HTTP.
about when to expose them. By default, Spring Boot exposes all enabled endpoints
over JMX but only the `health` and `info` endpoints over HTTP.
To change the endpoints that are exposed you can use the `expose` and `exclude` property
for the technology. For example, to only expose the `health` over JMX you would use:
To change the endpoints that are exposed, you can use the `expose` and `exclude` property
for the technology. For example, to only expose the `health` over JMX you would set the
following property:
.application.properties
[source,properties,indent=0]
@ -162,7 +161,7 @@ for the technology. For example, to only expose the `health` over JMX you would
----
The `*` character can be used to indicate all endpoints. For example, to expose everything
over HTTP except the `env` endpoint you would use:
over HTTP except the `env` endpoint, you would use the following properties:
.application.properties
[source,properties,indent=0]
@ -171,10 +170,10 @@ over HTTP except the `env` endpoint you would use:
management.endpoints.web.exclude=env
----
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
<<production-ready-endpoints-security, secure your endpoints>>.
TIP: If you want to implement your own strategy for when endpoints are exposed you can
TIP: If you want to implement your own strategy for when endpoints are exposed, you can
register an `EndpointFilter` bean.
@ -182,11 +181,11 @@ register an `EndpointFilter` bean.
[[production-ready-endpoints-security]]
=== Securing HTTP Endpoints
You should take care to secure HTTP endpoints in the same way that you would any other
sensitive URL. Spring Boot will not apply any security on your behalf, however, it does
provide some convenient ``RequestMatcher``s that can be used in combination with Spring
Security.
sensitive URL. Spring Boot does not apply any security on your behalf. However, it does
provide some convenient RequestMatcher` objects that can be used in combination with
Spring Security.
A typical Spring Security configuration could look something like this:
A typical Spring Security configuration might look something like the following example:
[source,java,indent=0]
----
@ -204,9 +203,11 @@ A typical Spring Security configuration could look something like this:
}
----
The above uses `EndpointRequest.toAnyEndpoint()` to match a request to any endpoint, then
ensure that all have the `ENDPOINT_ADMIN` role. Several other matcher methods are
also available on `EndpointRequest` (see the API documentation for details).
The preceding example uses `EndpointRequest.toAnyEndpoint()` to match a request to any
endpoint and then ensures that all have the `ENDPOINT_ADMIN` role. Several other matcher
methods are also available on `EndpointRequest`. See the API documentation
({spring-boot-actuator-api}/html[HTML] or
{spring-boot-actuator-api}/pdf/spring-boot-actuator-web-api.pdf[PDF]) for details.
If you deploy applications behind a firewall, you may prefer that all your actuator
endpoints can be accessed without requiring authentication. You can do so by changing the
@ -223,9 +224,9 @@ endpoints can be accessed without requiring authentication. You can do so by cha
[[production-ready-customizing-endpoints]]
=== Customizing Endpoints
Endpoints can be customized by using Spring properties. You can change whether an
endpoint is `enabled` and the amount of time it will cache responses.
endpoint is `enabled` and the amount of time for which it caches responses.
For example, the following `application.properties` changes the time-to-live of the
For example, the following `application.properties` file changes the time-to-live of the
`beans` endpoint to 10 seconds and also enables `shutdown`:
[source,properties,indent=0]
@ -248,9 +249,9 @@ disable _all_ endpoints except for `info`:
management.endpoint.info.enabled=true
----
NOTE: Disabled endpoints are removed entirely from the `ApplicationContext`. If you only
want to change the technologies over which an endpoint is exposed you can use the `expose`
and `exclude` properties (see <<production-ready-endpoints-exposing-endpoints>>).
NOTE: Disabled endpoints are removed entirely from the `ApplicationContext`. If you want
to change only the technologies over which an endpoint is exposed, you can use the
`expose` and `exclude` properties (see <<production-ready-endpoints-exposing-endpoints>>).
@ -269,13 +270,13 @@ disabled to prevent the possibility of a clash with other mappings.
[[production-ready-endpoint-custom-mapping]]
=== Actuator Web Endpoint Paths
By default, endpoints are exposed over HTTP under the `/actuator` path using ID of the
endpoint. For example, the `beans` endpoint is exposed under `/actuator/beans`. If you
want to map endpoints to a different path you can use the
`management.endpoints.web.path-mapping` property. You can also use
`management.endpoints.web.base-path` if you want change the base path.
By default, endpoints are exposed over HTTP under the `/actuator` path by using the ID of
the endpoint. For example, the `beans` endpoint is exposed under `/actuator/beans`. If you
want to map endpoints to a different path, you can use the
`management.endpoints.web.path-mapping` property. Also, if you want change the base path,
you can use `management.endpoints.web.base-path`.
Here's an example that remaps `/actuator/health` to `/healthcheck`:
The following example remaps `/actuator/health` to `/healthcheck`:
.application.properties
[source,properties,indent=0]
@ -289,8 +290,8 @@ Here's an example that remaps `/actuator/health` to `/healthcheck`:
[[production-ready-endpoint-cors]]
=== CORS Support
http://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing]
(CORS) is a http://www.w3.org/TR/cors/[W3C specification] that allows you to specify in a
flexible way what kind of cross domain requests are authorized. If you use Spring MVC or
(CORS) is a http://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.
CORS support is disabled by default and is only enabled once the
@ -303,29 +304,32 @@ configuration permits `GET` and `POST` calls from the `example.com` domain:
management.endpoints.web.cors.allowed-methods=GET,POST
----
TIP: See {sc-spring-boot-actuator-autoconfigure}/endpoint/web/CorsEndpointProperties.{sc-ext}[CorsEndpointProperties] for a complete list of options.
TIP: See
{sc-spring-boot-actuator-autoconfigure}/endpoint/web/CorsEndpointProperties.{sc-ext}[CorsEndpointProperties]
for a complete list of options.
[[production-ready-customizing-endpoints-programmatically]]
=== Adding Custom Endpoints
If you add a `@Bean` annotated with `@Endpoint`, any methods annotated with
`@ReadOperation`, `@WriteOperation` or `@DeleteOperation` are automatically exposed over
`@ReadOperation`, `@WriteOperation`, or `@DeleteOperation` are automatically exposed over
JMX and, in a web application, over HTTP as well.
You can also write technology specific endpoints by using `@JmxEndpoint` or
You can also write technology-specific endpoints by using `@JmxEndpoint` or
`@WebEndpoint`. These endpoints are filtered to their respective technologies. For
example, `@WebEndpoint` will be exposed only over HTTP and not over JMX.
example, `@WebEndpoint` is exposed only over HTTP and not over JMX.
Finally, it's possible to write technology specific extensions using
`@EndpointWebExtension` and `@EndpointJmxExtension`. These annotations allow you to
provide technology specific operations to augment an existing endpoint.
Finally, you can write technology-specific extensions by using `@EndpointWebExtension` and
`@EndpointJmxExtension`. These annotations let you provide technology-specific operations
to augment an existing endpoint.
TIP: If you add endpoints as a library feature, consider adding a configuration class
annotated with `@ManagementContextConfiguration` to `/META-INF/spring.factories` under the
key, `org.springframework.boot.actuate.autoconfigure.ManagementContextConfiguration`. If
you do so and if your users ask for a separate management port or address, the endpoint
moves to a child context with all the other web endpoints.
following key:
`org.springframework.boot.actuate.autoconfigure.ManagementContextConfiguration`. If you do
so and if your users ask for a separate management port or address, the endpoint moves to
a child context with all the other web endpoints.
@ -335,7 +339,7 @@ You can use health information to check the status of your running application.
often used by monitoring software to alert someone when a production system goes down.
The information exposed by the `health` endpoint depends on the
`management.endpoint.health.show-details` property. By default, the property's value is
`false` and a simple '`status`' message is returned. When the property's value is set to
`false` and a simple "`status`" message is returned. When the property's value is set to
`true`, additional details from the individual health indicators are also displayed.
Health information is collected from all
@ -393,7 +397,7 @@ The following `HealthIndicators` are auto-configured by Spring Boot when appropr
|Checks that a Solr server is up.
|===
TIP: It is possible to disable them all using the `management.health.defaults.enabled`
TIP: You can disable them all by setting the `management.health.defaults.enabled`
property.
@ -440,7 +444,7 @@ the `management.health.status.order` configuration property.
For example, assume a new `Status` with code `FATAL` is being used in one of your
`HealthIndicator` implementations. To configure the severity order, add the following
to your application properties:
property to your application properties:
[source,properties,indent=0]
----
@ -482,17 +486,17 @@ The following table shows the default status mappings for the built-in statuses:
[[reactive-health-indicators]]
==== Reactive Health Indicators
For reactive applications, such as those using Spring WebFlux, ReactiveHealthIndicators
provide a non-blocking contract for getting application health. Similar to a traditional
For reactive applications, such as those using Spring WebFlux, `ReactiveHealthIndicator`
provides a non-blocking contract for getting application health. Similar to a traditional
`HealthIndicator`, health information is collected from all
{sc-spring-boot-actuator}/health/ReactiveHealthIndicator.{sc-ext}[`ReactiveHealthIndicator`]
beans defined in your `ApplicationContext`. Regular HealthIndicators that do not check
against a reactive API are included and executed on the elastic scheduler.
beans defined in your `ApplicationContext`. Regular `HealthIndicator` beans that do not
check against a reactive API are included and executed on the elastic scheduler.
To provide custom health information from a reactive API, you can register Spring beans
that implement the
{sc-spring-boot-actuator}/health/ReactiveHealthIndicator.{sc-ext}[`ReactiveHealthIndicator`] interface.
The following code shows a sample `ReactiveHealthIndicator` implementation:
{sc-spring-boot-actuator}/health/ReactiveHealthIndicator.{sc-ext}[`ReactiveHealthIndicator`]
interface. The following code shows a sample `ReactiveHealthIndicator` implementation:
[source,java,indent=0]
----
@ -525,7 +529,7 @@ appropriate:
|Checks that a Redis server is up.
|===
TIP: Those reactive indicators replace the regular ones if necessary. Also, any
TIP: If necessary, reactive indicators replace the regular ones. Also, any
`HealthIndicator` that is not handled explicitly is wrapped automatically.
@ -535,34 +539,35 @@ TIP: Those reactive indicators replace the regular ones if necessary. Also, any
Application information exposes various information collected from all
{sc-spring-boot-actuator}/info/InfoContributor.{sc-ext}[`InfoContributor`] beans defined
in your `ApplicationContext`. Spring Boot includes a number of auto-configured
`InfoContributors`, and you can write your own.
`InfoContributor` beans, and you can write your own.
[[production-ready-application-info-autoconfigure]]
==== Auto-configured InfoContributors
The following `InfoContributors` are auto-configured by Spring Boot, when appropriate:
The following `InfoContributor ` beans are auto-configured by Spring Boot, when
appropriate:
[cols="1,4"]
|===
|Name |Description
|{sc-spring-boot-actuator}/info/EnvironmentInfoContributor.{sc-ext}[`EnvironmentInfoContributor`]
|Expose any key from the `Environment` under the `info` key.
|Exposes any key from the `Environment` under the `info` key.
|{sc-spring-boot-actuator}/info/GitInfoContributor.{sc-ext}[`GitInfoContributor`]
|Expose git information if a `git.properties` file is available.
|Exposes git information if a `git.properties` file is available.
|{sc-spring-boot-actuator}/info/BuildInfoContributor.{sc-ext}[`BuildInfoContributor`]
|Expose build information if a `META-INF/build-info.properties` file is available.
|Exposes build information if a `META-INF/build-info.properties` file is available.
|===
TIP: It is possible to disable them all using the `management.info.defaults.enabled`
TIP: It is possible to disable them all by setting the `management.info.defaults.enabled`
property.
[[production-ready-application-info-env]]
==== 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.
properties. All `Environment` properties under the `info` key are automatically exposed.
For example, you could add the following settings to your `application.properties` file:
[source,properties,indent=0]
@ -593,7 +598,7 @@ Assuming you use Maven, you could rewrite the preceding example as follows:
==== 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 `git.branch`, `git.commit.id` and
`GitProperties` bean is available, the `git.branch`, `git.commit.id`, and
`git.commit.time` properties are exposed.
TIP: A `GitProperties` bean is auto-configured if a `git.properties` file is available at
@ -668,7 +673,7 @@ enabled endpoints to be exposed over HTTP. The default convention is to use the
the endpoint with a prefix of `/actuator` as the URL path. For example, `health` is
exposed as `/actuator/health`.
TIP: Actuator is supported natively with Spring MVC, Spring WebFlux and Jersey.
TIP: Actuator is supported natively with Spring MVC, Spring WebFlux, and Jersey.
@ -685,11 +690,11 @@ management endpoint, as shown in the following example:
----
The preceding `application.properties` example changes the endpoint from
`/actuator/{id}` to `/manage/{id}` (e.g. `/manage/info`).
`/actuator/{id}` to `/manage/{id}` (for example, `/manage/info`).
NOTE: Unless the management port has been configured to
<<production-ready-customizing-management-server-port,expose endpoints using a different
HTTP port>>, `management.endpoints.web.base-path` is relative to
<<production-ready-customizing-management-server-port,expose endpoints by using a
different HTTP port>>, `management.endpoints.web.base-path` is relative to
`server.servlet.context-path`. If `management.server.port` is configured,
`management.endpoints.web.base-path` is relative to
`management.server.servlet.context-path`.
@ -699,7 +704,7 @@ HTTP port>>, `management.endpoints.web.base-path` is relative to
[[production-ready-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,
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.
You can set the `management.server.port` property to change the HTTP port, as shown in
@ -713,15 +718,16 @@ the following example:
Since your management port is often protected by a firewall and not exposed to the
public, you might not need security on the management endpoints, even if your main
application is secure. In that case, you should have Spring Security on the classpath,
and you can disable management security as follows:
and you can disable management security, as follows:
[source,properties,indent=0]
----
management.security.enabled=false
----
(If you do not have Spring Security on the classpath, there is no need to explicitly
disable the management security in this way. Doing so might even break the application.)
CAUTION: If you do not have Spring Security on the classpath, there is no need to
explicitly disable the management security in this way. Doing so might even break the
application.
@ -729,7 +735,7 @@ disable the management security in this way. Doing so might even break the appli
=== 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 via HTTP while the main application uses HTTPS,
so lets a management server be available over HTTP while the main application uses HTTPS,
as shown in the following property settings:
[source,properties,indent=0]
@ -766,7 +772,7 @@ the `management.server.address` property. Doing so can be useful if you want to
only on an internal or ops-facing network or to listen only for connections from
`localhost`.
NOTE: You can only listen on a different address if the port is different from the main
NOTE: You can listen on a different address only when the port differs from the main
server port.
The following example `application.properties` does not allow remote management
@ -802,7 +808,7 @@ the `org.springframework.boot` domain.
[[production-ready-custom-mbean-names]]
=== Customizing MBean Names
The name of the MBean is usually generated from the `id` of the endpoint. For example the
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`.
If your application contains more than one Spring `ApplicationContext`, you may find that
@ -854,9 +860,9 @@ server.
[[production-ready-customizing-jolokia]]
==== Customizing Jolokia
Jolokia has a number of settings that you would traditionally configure using servlet
parameters. With Spring Boot, you can use your `application.properties`. Prefix the
parameter with `management.jolokia.config.`, as shown in the following example:
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. To do so,
prefix the parameter with `management.jolokia.config.`, as shown in the following example:
[source,properties,indent=0]
----
@ -900,8 +906,8 @@ one of:
[[production-ready-logger-configuration]]
=== Configure a Logger
In order to configure a given logger, you `POST` a partial entity to the resource's URI,
as shown in the following example:
To configure a given logger, `POST` a partial entity to the resource's URI, as shown in
the following example:
[source,json,indent=0]
----
@ -910,7 +916,7 @@ as shown in the following example:
}
----
TIP: To "reset" the specific level of the logger (and use the default configuration
TIP: To "`reset`" the specific level of the logger (and use the default configuration
instead), you can pass a value of `null` as the `configuredLevel`.
@ -919,7 +925,7 @@ instead), you can pass a value of `null` as the `configuredLevel`.
== Metrics
Spring Boot Actuator provides dependency management and auto-configuration for
https://micrometer.io[Micrometer], an application metrics facade that supports numerous
monitoring systems:
monitoring systems, including:
- https://github.com/Netflix/atlas[Atlas]
- https://www.datadoghq.com[Datadog]
@ -928,6 +934,10 @@ monitoring systems:
- https://www.influxdata.com[Influx]
- https://prometheus.io[Prometheus]
NOTE: At the time of this writing, the number of monitoring systems supported by
Micrometer is growing rapidly. See the https://micrometer.io[Micrometer project] for more
information.
Micrometer provides a separate module for each supported monitoring system. Depending on
one (or more) of these modules is sufficient to get started with Micrometer in your
Spring Boot application. To learn more about Micrometer's capabilities, please refer to
@ -951,10 +961,10 @@ customized by setting the `management.metrics.web.server.requests-metrics-name`
==== Spring MVC Metric Tags
By default, Spring MVC-related metrics are tagged with the following information:
- The request's method.
- The request's URI (templated if possible).
- The simple class name of any exception that was thrown while handling the request.
- The response's status.
* The request's method.
* The request's URI (templated if possible).
* The simple class name of any exception that was thrown while handling the request.
* The response's status.
To customize the tags, provide a `@Bean` that implements `WebMvcTagsProvider`.
@ -971,23 +981,23 @@ the name by setting the `management.metrics.web.server.requests-metrics-name` pr
[[production-ready-metrics-web-flux-tags]]
==== WebFlux Metric Tags
==== WebFlux Metrics Tags
By default, WebFlux-related metrics for the annotation-based programming model are tagged
with the following information:
- The request's method.
- The request's URI (templated if possible).
- The simple class name of any exception that was thrown while handling the request.
- The response's status.
* The request's method.
* The request's URI (templated if possible).
* The simple class name of any exception that was thrown while handling the request.
* The response's status.
To customize the tags, provide a `@Bean` that implements `WebFluxTagsProvider`.
By default, metrics for the functional programming model are tagged with the following
information:
- The request's method
- The request's URI (templated if possible).
- The response's status.
* The request's method
* The request's URI (templated if possible).
* The response's status.
To customize the tags, use the `defaultTags` method on your `RouterFunctionMetrics`
instance.
@ -1010,10 +1020,10 @@ customized by setting the `management.metrics.web.client.requests-metrics-name`
By default, metrics generated by an instrumented `RestTemplate` are tagged with the
following information:
- The request's method.
- The request's URI (templated if possible).
- The response's status.
- The request URI's host.
* The request's method.
* The request's URI (templated if possible).
* The response's status.
* The request URI's host.
@ -1042,15 +1052,15 @@ is required. A `CacheMetricsRegistrar` bean is made available to make that proce
[[production-ready-metrics-jdbc]]
=== DataSource metrics
Auto-configuration will enable the instrumentation of all available ``DataSource``s with a
metric named `data.source`. Data source instrumentation results in gauges representing
the currently active, maximum allowed, and minimum allowed connections in the pool. Each
of these gauges has a name which is prefixed by `data.source` by default. The prefix can
be customized by using the `management.metrics.jdbc.datasource-metric-name` property.
Metrics will also be tagged by the name of the `DataSource` computed based on the bean
name.
=== DataSource Metrics
Auto-configuration enables the instrumentation of all available ``DataSource`` objects
with a metric named `data.source`. Data source instrumentation results in gauges
representing the currently active, maximum allowed, and minimum allowed connections in the
pool. Each of these gauges has a name that is prefixed by `data.source` by default. The
prefix can be customized by setting the `management.metrics.jdbc.datasource-metric-name`
property.
Metrics are also tagged by the name of the `DataSource` computed based on the bean name.
@ -1115,9 +1125,9 @@ Auto-configuration enables binding of a number of Spring Integration-related met
[[production-ready-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
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. To customize published
security events, you can provide your own implementations of
`AbstractAuthenticationAuditListener` and `AbstractAuthorizationAuditListener`.
@ -1211,18 +1221,20 @@ In the `spring-boot` module, you can find two classes to create files that are o
useful for process monitoring:
* `ApplicationPidFileWriter` creates a file containing the application PID (by default,
in the application directory with the file name, `application.pid`).
in the application directory with a file name of `application.pid`).
* `EmbeddedServerPortFileWriter` creates a file (or files) containing the ports of the
embedded server (by default, in the application directory with the file name
embedded server (by default, in the application directory with a file name of
`application.port`).
By default, these writers are not activated, but you can enable them in one of the ways
described in the next section.
By default, these writers are not activated, but you can enable:
* <<production-ready-process-monitoring-configuration,By Extending Configuration>>
* <<production-ready-process-monitoring-programmatically>>
[[production-ready-process-monitoring-configuration]]
=== Extend 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:

47
spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc
Unescape Escape View File

@ -79,7 +79,7 @@ using, as follows:
[[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 don't need any external Groovy installation.
is completely self-contained, so you do not need any external Groovy installation.
The following example shows a "`hello world`" web application written in Groovy:
@ -97,14 +97,14 @@ The following example shows a "`hello world`" web application written in Groovy:
}
----
To compile and run the application type the following command:
To compile and run the application, type the following command:
[indent=0,subs="verbatim,quotes,attributes"]
----
$ spring run hello.groovy
----
To pass command-line arguments to the application, use a `--` to separate the commands
To pass command-line arguments to the application, use `--` to separate the commands
from the "`spring`" command arguments, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"]
@ -186,10 +186,11 @@ in the Spring Boot CLI source code to understand exactly how customizations are
==== 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. Note that
the default metadata is tied to the version of the CLI that you use – it changes only when
you move to a new version of the CLI, putting you in control of when the versions of your
dependencies may change. A table showing the dependencies and their versions that are
Boot's default dependency metadata to deduce the artifact's group and version.
NOTE: The default metadata is tied to the version of the CLI that you use. it changes only
when you move to a new version of the CLI, putting you in control of when the versions of
your dependencies may change. A table showing the dependencies and their versions that are
included in the default metadata can be found in the <<appendix-dependency-versions,
appendix>>.
@ -242,8 +243,8 @@ as shown in the following example:
"com.example.another-bom:1.0.0"])
----
The preceding example indicates that dependency management in `another-bom` overrides the
dependency management in `custom-bom`.
The preceding example indicates that the dependency management in `another-bom` overrides
the dependency management in `custom-bom`.
You can use `@DependencyManagementBom` anywhere that you can use `@Grab`. However, to
ensure consistent ordering of the dependency management, you can use
@ -282,10 +283,10 @@ jar file, as shown in the following example:
The resulting jar contains the classes produced by compiling the application and all of
the application's dependencies so that it can then be run by using `java -jar`. The jar
file also contains entries from the application's classpath. You can add explicit paths to
the jar by using `--include` and `--exclude`. Both are comma-separated, and both accept
prefixes, in the form of "`+`" and "`-`", to signify that they should be removed from the
defaults. The default includes are as follows:
file also contains entries from the application's classpath. You can add and remove
explicit paths to the jar by using `--include` and `--exclude`. Both are comma-separated,
and both accept prefixes, in the form of "`+`" and "`-`", to signify that they should be
removed from the defaults. The default includes are as follows:
[indent=0]
----
@ -399,8 +400,8 @@ In addition to installing the artifacts identified by the coordinates you supply
the artifacts' dependencies are also installed.
To uninstall a dependency, use the `uninstall` command. As with the `install` command, it
takes one or more sets of artifact coordinates in the format `group:artifact:version`, as
shown in the following example:
takes one or more sets of artifact coordinates in the format of `group:artifact:version`,
as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"]
----
@ -462,14 +463,14 @@ The Spring Boot CLI uses Aether, Maven's dependency resolution engine, to resolv
dependencies. The CLI makes use of the Maven configuration found in `~/.m2/settings.xml`
to configure Aether. The following configuration settings are honored by the CLI:
* Offline
* Mirrors
* Servers
* Proxies
* Profiles
** Activation
** Repositories
* Active profiles
* Offline
* Mirrors
* Servers
* Proxies
* Profiles
** Activation
** Repositories
* Active profiles
See https://maven.apache.org/settings.html[Maven's settings documentation] for further
information.

990
spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View File

File diff suppressed because it is too large Load Diff

33
spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
Unescape Escape View File

@ -30,7 +30,7 @@ systems (Ant, for example), but they are not particularly well supported.
=== 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 is managing that for you. When you upgrade Spring
build configuration, as Spring Boot manages that for you. When you upgrade Spring
Boot itself, these dependencies are upgraded as well in a consistent way.
NOTE: You can still specify a version and override Spring Boot's recommendations if you
@ -76,8 +76,8 @@ style placeholders (`${...}`), the Maven filtering is changed to use `@..@` plac
[[using-boot-maven-parent-pom]]
==== Inheriting the Starter Parent
To configure your project to inherit from the `spring-boot-starter-parent` set the
`parent`, as follows:
To configure your project to inherit from the `spring-boot-starter-parent`, set the
`parent` as follows:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
@ -273,7 +273,7 @@ _<<howto.adoc#howto-build-an-executable-archive-with-ant>>_ "`How-to`" .
[[using-boot-starter]]
=== 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 technology that you
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. For example, if you want to get started using Spring and JPA for database
access, include the `spring-boot-starter-data-jpa` dependency in your project.
@ -285,9 +285,9 @@ running quickly and with a consistent, supported set of managed transitive depen
****
All **official** starters follow a similar naming pattern; `+spring-boot-starter-*+`,
where `+*+` is a particular type of application. This naming structure is intended to
help when you need to find a starter. The Maven integration in many IDEs allow you 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 simply hit `ctrl-space` in the POM editor and type
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
@ -636,6 +636,7 @@ following example:
=== 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.
The following example shows a typical Maven command to run a Spring Boot application:
[indent=0,subs="attributes"]
----
@ -682,7 +683,7 @@ http://zeroturnaround.com/software/jrebel/[JRebel] can be used.
The
`spring-boot-devtools` module also includes support for quick application restarts.
See the <<using-boot-devtools>> section below and the
See the <<using-boot-devtools>> section later in this chapter and the
<<howto.adoc#howto-hotswapping, Hot swapping "`How-to`">> for details.
@ -716,10 +717,10 @@ listings for Maven and Gradle:
----
NOTE: Developer tools are automatically disabled when running a fully packaged
application. If your application is launched using `java -jar` or if it is started from a
application. If your application is launched from `java -jar` or if it is started from a
special classloader, then it is considered a "`production application`". Flagging the
dependency as optional is a best practice that prevents devtools from being transitively
applied to other modules using your project. Gradle does not support `optional`
applied to other modules that use your project. Gradle does not support `optional`
dependencies out-of-the-box, so you may want to have a look at the
{propdeps-plugin}[`propdeps-plugin`].
@ -852,7 +853,7 @@ You may want your application to be restarted or reloaded when you make changes
that are not on the classpath. To do so, use the
`spring.devtools.restart.additional-paths` property to configure additional paths to
watch for changes. You can use the `spring.devtools.restart.exclude` property
<<using-boot-devtools-restart-exclude, described above>> to control whether changes
<<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>>.
@ -865,7 +866,7 @@ If you do not want to use the restart feature, you can disable it by using the
your `application.properties` (doing so still initializes the restart classloader, but it
does not watch for file changes).
If you need to _completely_ disable restart support (for example, because it doesn't work
If you need to _completely_ disable restart support (for example, because it does not work
with a specific library), you need to set the `spring.devtools.restart.enabled` `System`
property to `false` before calling `SpringApplication.run(...)`, as shown in the
following example:
@ -885,7 +886,7 @@ following example:
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. Changing the file only triggers the check and the restart will only occur if
check. Changing the file only triggers the check and the restart only occurs if
Devtools has detected it has to do something. The trigger file can be updated manually or
with an IDE plugin.
@ -900,9 +901,9 @@ in the same way.
[[using-boot-devtools-customizing-classload]]
==== Customizing the Restart Classloader
As described in the <<using-spring-boot-restart-vs-reload>> section above, restart
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. However, sometimes it can cause classloading issues.
approach works well. However, it can sometimes cause classloading issues.
By default, any open project in your IDE is loaded with the "`restart`" classloader, and
any regular `.jar` file is loaded with the "`base`" classloader. If you work on a
@ -924,7 +925,7 @@ pattern that is applied to the classpath, as shown in the following example:
NOTE: All property keys must be unique. As long as a property starts with
`restart.include.` or `restart.exclude.` it is considered.
TIP: All `META-INF/spring-devtools.properties` from the classpath will be loaded. You can
TIP: All `META-INF/spring-devtools.properties` from the classpath are loaded. You can
package files inside your project, or in the libraries that the project consumes.
@ -977,7 +978,7 @@ property:
[[using-boot-devtools-remote]]
=== Remote Applications
The Spring Boot developer tools are not just limited to local development. You can also
The Spring Boot developer tools are not limited to local development. You can also
use several features when running applications remotely. Remote support is opt-in. To
enable it, you need to make sure that `devtools` is included in the repackaged archive,
as shown in the following listing:

Write Preview
Loading…
Cancel
Save