Phillip Webb
parent
bb8188b681
commit
33c6c600a9
|
|
@ -181,33 +181,33 @@ task aggregatedJavadoc(type: Javadoc) {
|
|||
|
||||
task documentTestSlices(type: org.springframework.boot.build.test.autoconfigure.DocumentTestSlices) {
|
||||
testSlices = configurations.testSlices
|
||||
outputFile = file("${buildDir}/docs/generated/test-slice-auto-configuration.adoc")
|
||||
outputFile = file("${buildDir}/docs/generated/test-auto-configuration/documented-slices.adoc")
|
||||
}
|
||||
|
||||
task documentStarters(type: org.springframework.boot.build.starters.DocumentStarters) {
|
||||
outputDir = file("${buildDir}/docs/generated/starters/")
|
||||
outputDir = file("${buildDir}/docs/generated/using/starters/")
|
||||
}
|
||||
|
||||
task documentAutoConfigurationClasses(type: org.springframework.boot.build.autoconfigure.DocumentAutoConfigurationClasses) {
|
||||
autoConfiguration = configurations.autoConfiguration
|
||||
outputDir = file("${buildDir}/docs/generated/auto-configuration-classes/")
|
||||
outputDir = file("${buildDir}/docs/generated/auto-configuration-classes/documented-auto-configuration-classes/")
|
||||
}
|
||||
|
||||
task documentDependencyVersions(type: org.springframework.boot.build.constraints.DocumentConstrainedVersions) {
|
||||
dependsOn dependencyVersions
|
||||
constrainedVersions.set(providers.provider { dependencyVersions.constrainedVersions })
|
||||
outputFile = file("${buildDir}/docs/generated/generated-dependency-versions.adoc")
|
||||
outputFile = file("${buildDir}/docs/generated/dependency-versions/documented-coordinates.adoc")
|
||||
}
|
||||
|
||||
task documentVersionProperties(type: org.springframework.boot.build.constraints.DocumentVersionProperties) {
|
||||
dependsOn dependencyVersions
|
||||
versionProperties.set(providers.provider { dependencyVersions.versionProperties})
|
||||
outputFile = file("${buildDir}/docs/generated/generated-version-properties.adoc")
|
||||
outputFile = file("${buildDir}/docs/generated/dependency-versions/documented-properties.adoc")
|
||||
}
|
||||
|
||||
task documentConfigurationProperties(type: org.springframework.boot.build.context.properties.DocumentConfigurationProperties) {
|
||||
configurationPropertyMetadata = configurations.configurationProperties
|
||||
outputDir = file("${buildDir}/docs/generated/config-docs/")
|
||||
outputDir = file("${buildDir}/docs/generated/application-properties/documented-application-properties/")
|
||||
}
|
||||
|
||||
tasks.withType(org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask) {
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,18 @@
|
|||
[[actuator.auditing]]
|
||||
== Auditing
|
||||
Once Spring Security is in play, Spring Boot Actuator has a flexible audit framework that publishes events (by default, "`authentication success`", "`failure`" and "`access denied`" exceptions).
|
||||
This feature can be very useful for reporting and for implementing a lock-out policy based on authentication failures.
|
||||
|
||||
Auditing can be enabled by providing a bean of type `AuditEventRepository` in your application's configuration.
|
||||
For convenience, Spring Boot offers an `InMemoryAuditEventRepository`.
|
||||
`InMemoryAuditEventRepository` has limited capabilities and we recommend using it only for development environments.
|
||||
For production environments, consider creating your own alternative `AuditEventRepository` implementation.
|
||||
|
||||
|
||||
|
||||
[[actuator.auditing.custom]]
|
||||
=== Custom Auditing
|
||||
To customize published security events, you can provide your own implementations of `AbstractAuthenticationAuditListener` and `AbstractAuthorizationAuditListener`.
|
||||
|
||||
You can also use the audit services for your own business events.
|
||||
To do so, either inject the `AuditEventRepository` bean into your own components and use that directly or publish an `AuditApplicationEvent` with the Spring `ApplicationEventPublisher` (by implementing `ApplicationEventPublisherAware`).
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
[[actuator.cloud-foundry]]
|
||||
== Cloud Foundry Support
|
||||
Spring Boot's actuator module includes additional support that is activated when you deploy to a compatible Cloud Foundry instance.
|
||||
The `/cloudfoundryapplication` path provides an alternative secured route to all `@Endpoint` beans.
|
||||
|
||||
The extended support lets Cloud Foundry management UIs (such as the web application that you can use to view deployed applications) be augmented with Spring Boot actuator information.
|
||||
For example, an application status page may include full health information instead of the typical "`running`" or "`stopped`" status.
|
||||
|
||||
NOTE: The `/cloudfoundryapplication` path is not directly accessible to regular users.
|
||||
In order to use the endpoint, a valid UAA token must be passed with the request.
|
||||
|
||||
|
||||
|
||||
[[actuator.cloud-foundry.disable]]
|
||||
=== Disabling Extended Cloud Foundry Actuator Support
|
||||
If you want to fully disable the `/cloudfoundryapplication` endpoints, you can add the following setting to your `application.properties` file:
|
||||
|
||||
|
||||
.application.properties
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
cloudfoundry:
|
||||
enabled: false
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.cloud-foundry.ssl]]
|
||||
=== Cloud Foundry Self-signed Certificates
|
||||
By default, the security verification for `/cloudfoundryapplication` endpoints makes SSL calls to various Cloud Foundry services.
|
||||
If your Cloud Foundry UAA or Cloud Controller services use self-signed certificates, you need to set the following property:
|
||||
|
||||
.application.properties
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
cloudfoundry:
|
||||
skip-ssl-validation: true
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.cloud-foundry.custom-context-path]]
|
||||
=== Custom Context Path
|
||||
If the server's context-path has been configured to anything other than `/`, the Cloud Foundry endpoints will not be available at the root of the application.
|
||||
For example, if `server.servlet.context-path=/app`, Cloud Foundry endpoints will be available at `/app/cloudfoundryapplication/*`.
|
||||
|
||||
If you expect the Cloud Foundry endpoints to always be available at `/cloudfoundryapplication/*`, regardless of the server's context-path, you will need to explicitly configure that in your application.
|
||||
The configuration will differ depending on the web server in use.
|
||||
For Tomcat, the following configuration can be added:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-productionreadyfeatures}/cloudfoundry/CloudFoundryCustomContextPathConfiguration.java[tag=*]
|
||||
----
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
[[actuator.enabling]]
|
||||
== Enabling Production-ready Features
|
||||
The {spring-boot-code}/spring-boot-project/spring-boot-actuator[`spring-boot-actuator`] module provides all of Spring Boot's production-ready features.
|
||||
The recommended way to enable the features is to add a dependency on the `spring-boot-starter-actuator` '`Starter`'.
|
||||
|
||||
.Definition of Actuator
|
||||
****
|
||||
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.
|
||||
****
|
||||
|
||||
To add the actuator to a Maven based project, add the following '`Starter`' dependency:
|
||||
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-actuator</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
----
|
||||
|
||||
For Gradle, use the following declaration:
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
dependencies {
|
||||
implementation 'org.springframework.boot:spring-boot-starter-actuator'
|
||||
}
|
||||
----
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,99 @@
|
|||
[[actuator.jmx]]
|
||||
== Monitoring and Management over JMX
|
||||
Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications.
|
||||
By default, this feature is not enabled and can be turned on by setting the configuration property configprop:spring.jmx.enabled[] to `true`.
|
||||
Spring Boot exposes management endpoints as JMX MBeans under the `org.springframework.boot` domain by default.
|
||||
To Take full control over endpoints registration in the JMX domain, consider registering your own `EndpointObjectNameFactory` implementation.
|
||||
|
||||
|
||||
|
||||
[[actuator.jmx.custom-mbean-names]]
|
||||
=== Customizing MBean Names
|
||||
The name of the MBean is usually generated from the `id` of the endpoint.
|
||||
For example, the `health` endpoint is exposed as `org.springframework.boot:type=Endpoint,name=Health`.
|
||||
|
||||
If your application contains more than one Spring `ApplicationContext`, you may find that names clash.
|
||||
To solve this problem, you can set the configprop:spring.jmx.unique-names[] property to `true` so that MBean names are always unique.
|
||||
|
||||
You can also customize the JMX domain under which endpoints are exposed.
|
||||
The following settings show an example of doing so in `application.properties`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
jmx:
|
||||
unique-names: true
|
||||
management:
|
||||
endpoints:
|
||||
jmx:
|
||||
domain: "com.example.myapp"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.jmx.disable-jmx-endpoints]]
|
||||
=== Disabling JMX Endpoints
|
||||
If you do not want to expose endpoints over JMX, you can set the configprop:management.endpoints.jmx.exposure.exclude[] property to `*`, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
endpoints:
|
||||
jmx:
|
||||
exposure:
|
||||
exclude: "*"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.jmx.jolokia]]
|
||||
=== Using Jolokia for JMX over HTTP
|
||||
Jolokia is a JMX-HTTP bridge that provides an alternative method of accessing JMX beans.
|
||||
To use Jolokia, include a dependency to `org.jolokia:jolokia-core`.
|
||||
For example, with Maven, you would add the following dependency:
|
||||
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.jolokia</groupId>
|
||||
<artifactId>jolokia-core</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
The Jolokia endpoint can then be exposed by adding `jolokia` or `*` to the configprop:management.endpoints.web.exposure.include[] property.
|
||||
You can then access it by using `/actuator/jolokia` on your management HTTP server.
|
||||
|
||||
NOTE: The Jolokia endpoint exposes Jolokia's servlet as an actuator endpoint.
|
||||
As a result, it is specific to servlet environments such as Spring MVC and Jersey.
|
||||
The endpoint will not be available in a WebFlux application.
|
||||
|
||||
|
||||
|
||||
[[actuator.jmx.jolokia.customizing]]
|
||||
==== Customizing Jolokia
|
||||
Jolokia has a number of settings that you would traditionally configure by setting servlet parameters.
|
||||
With Spring Boot, you can use your `application.properties` file.
|
||||
To do so, prefix the parameter with `management.endpoint.jolokia.config.`, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
endpoint:
|
||||
jolokia:
|
||||
config:
|
||||
debug: true
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.jmx.jolokia.disabling]]
|
||||
==== Disabling Jolokia
|
||||
If you use Jolokia but do not want Spring Boot to configure it, set the configprop:management.endpoint.jolokia.enabled[] property to `false`, as follows:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
endpoint:
|
||||
jolokia:
|
||||
enabled: false
|
||||
----
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
[[actuator.loggers]]
|
||||
== Loggers
|
||||
Spring Boot Actuator includes the ability to view and configure the log levels of your application at runtime.
|
||||
You can view either the entire list or an individual logger's configuration, which is made up of both the explicitly configured logging level as well as the effective logging level given to it by the logging framework.
|
||||
These levels can be one of:
|
||||
|
||||
* `TRACE`
|
||||
* `DEBUG`
|
||||
* `INFO`
|
||||
* `WARN`
|
||||
* `ERROR`
|
||||
* `FATAL`
|
||||
* `OFF`
|
||||
* `null`
|
||||
|
||||
`null` indicates that there is no explicit configuration.
|
||||
|
||||
|
||||
|
||||
[[actuator.loggers.configure]]
|
||||
=== Configure a Logger
|
||||
To configure a given logger, `POST` a partial entity to the resource's URI, as shown in the following example:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{
|
||||
"configuredLevel": "DEBUG"
|
||||
}
|
||||
----
|
||||
|
||||
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`.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,148 @@
|
|||
[[actuator.monitoring]]
|
||||
== Monitoring and Management over HTTP
|
||||
If you are developing a web application, Spring Boot Actuator auto-configures all enabled endpoints to be exposed over HTTP.
|
||||
The default convention is to use the `id` of the endpoint with a prefix of `/actuator` as the URL path.
|
||||
For example, `health` is exposed as `/actuator/health`.
|
||||
|
||||
TIP: Actuator is supported natively with Spring MVC, Spring WebFlux, and Jersey.
|
||||
If both Jersey and Spring MVC are available, Spring MVC will be used.
|
||||
|
||||
NOTE: Jackson is a required dependency in order to get the correct JSON responses as documented in the API documentation ({spring-boot-actuator-restapi-docs}[HTML] or {spring-boot-actuator-restapi-pdfdocs}[PDF]).
|
||||
|
||||
|
||||
|
||||
[[actuator.monitoring.customizing-management-server-context-path]]
|
||||
=== Customizing the Management Endpoint Paths
|
||||
Sometimes, it is useful to customize the prefix for the management endpoints.
|
||||
For example, your application might already use `/actuator` for another purpose.
|
||||
You can use the configprop:management.endpoints.web.base-path[] property to change the prefix for your management endpoint, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
base-path: "/manage"
|
||||
----
|
||||
|
||||
The preceding `application.properties` example changes the endpoint from `/actuator/\{id}` to `/manage/\{id}` (for example, `/manage/info`).
|
||||
|
||||
NOTE: Unless the management port has been configured to <<actuator#actuator.monitoring.customizing-management-server-port,expose endpoints by using a different HTTP port>>, `management.endpoints.web.base-path` is relative to `server.servlet.context-path` (Servlet web applications) or `spring.webflux.base-path` (reactive web applications).
|
||||
If `management.server.port` is configured, `management.endpoints.web.base-path` is relative to `management.server.base-path`.
|
||||
|
||||
If you want to map endpoints to a different path, you can use the configprop:management.endpoints.web.path-mapping[] property.
|
||||
|
||||
The following example remaps `/actuator/health` to `/healthcheck`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
base-path: "/"
|
||||
path-mapping:
|
||||
health: "healthcheck"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.monitoring.customizing-management-server-port]]
|
||||
=== Customizing the Management Server Port
|
||||
Exposing management endpoints by using the default HTTP port is a sensible choice for cloud-based deployments.
|
||||
If, however, your application runs inside your own data center, you may prefer to expose endpoints by using a different HTTP port.
|
||||
|
||||
You can set the configprop:management.server.port[] property to change the HTTP port, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
server:
|
||||
port: 8081
|
||||
----
|
||||
|
||||
NOTE: On Cloud Foundry, applications only receive requests on port 8080 for both HTTP and TCP routing, by default.
|
||||
If you want to use a custom management port on Cloud Foundry, you will need to explicitly set up the application's routes to forward traffic to the custom port.
|
||||
|
||||
|
||||
|
||||
[[actuator.monitoring.management-specific-ssl]]
|
||||
=== Configuring Management-specific SSL
|
||||
When configured to use a custom port, the management server can also be configured with its own SSL by using the various `management.server.ssl.*` properties.
|
||||
For example, doing so lets a management server be available over HTTP while the main application uses HTTPS, as shown in the following property settings:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
server:
|
||||
port: 8443
|
||||
ssl:
|
||||
enabled: true
|
||||
key-store: "classpath:store.jks"
|
||||
key-password: secret
|
||||
management:
|
||||
server:
|
||||
port: 8080
|
||||
ssl:
|
||||
enabled: false
|
||||
----
|
||||
|
||||
Alternatively, both the main server and the management server can use SSL but with different key stores, as follows:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
server:
|
||||
port: 8443
|
||||
ssl:
|
||||
enabled: true
|
||||
key-store: "classpath:main.jks"
|
||||
key-password: "secret"
|
||||
management:
|
||||
server:
|
||||
port: 8080
|
||||
ssl:
|
||||
enabled: true
|
||||
key-store: "classpath:management.jks"
|
||||
key-password: "secret"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.monitoring.customizing-management-server-address]]
|
||||
=== Customizing the Management Server Address
|
||||
You can customize the address that the management endpoints are available on by setting the configprop:management.server.address[] property.
|
||||
Doing so can be useful if you want to listen only on an internal or ops-facing network or to listen only for connections from `localhost`.
|
||||
|
||||
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 connections:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
server:
|
||||
port: 8081
|
||||
address: "127.0.0.1"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.monitoring.disabling-http-endpoints]]
|
||||
=== Disabling HTTP Endpoints
|
||||
If you do not want to expose endpoints over HTTP, you can set the management port to `-1`, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
server:
|
||||
port: -1
|
||||
----
|
||||
|
||||
This can be achieved using the configprop:management.endpoints.web.exposure.exclude[] property as well, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
exclude: "*"
|
||||
----
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
[[actuator.process-monitoring]]
|
||||
== Process Monitoring
|
||||
In the `spring-boot` module, you can find two classes to create files that are often useful for process monitoring:
|
||||
|
||||
* `ApplicationPidFileWriter` creates a file containing the application PID (by default, in the application directory with a file name of `application.pid`).
|
||||
* `WebServerPortFileWriter` creates a file (or files) containing the ports of the running web 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:
|
||||
|
||||
* <<actuator#actuator.process-monitoring.configuration,By Extending Configuration>>
|
||||
* <<actuator#actuator.process-monitoring.programmatically>>
|
||||
|
||||
|
||||
|
||||
[[actuator.process-monitoring.configuration]]
|
||||
=== Extending Configuration
|
||||
In the `META-INF/spring.factories` file, you can activate the listener(s) that writes a PID file, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
org.springframework.context.ApplicationListener=\
|
||||
org.springframework.boot.context.ApplicationPidFileWriter,\
|
||||
org.springframework.boot.web.context.WebServerPortFileWriter
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[actuator.process-monitoring.programmatically]]
|
||||
=== Programmatically
|
||||
You can also activate a listener by invoking the `SpringApplication.addListeners(...)` method and passing the appropriate `Writer` object.
|
||||
This method also lets you customize the file name and path in the `Writer` constructor.
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
[[actuator.tracing]]
|
||||
== HTTP Tracing
|
||||
HTTP Tracing can be enabled by providing a bean of type `HttpTraceRepository` in your application's configuration.
|
||||
For convenience, Spring Boot offers an `InMemoryHttpTraceRepository` that stores traces for the last 100 request-response exchanges, by default.
|
||||
`InMemoryHttpTraceRepository` is limited compared to other tracing solutions and we recommend using it only for development environments.
|
||||
For production environments, use of a production-ready tracing or observability solution, such as Zipkin or Spring Cloud Sleuth, is recommended.
|
||||
Alternatively, create your own `HttpTraceRepository` that meets your needs.
|
||||
|
||||
The `httptrace` endpoint can be used to obtain information about the request-response exchanges that are stored in the `HttpTraceRepository`.
|
||||
|
||||
|
||||
|
||||
[[actuator.tracing.custom]]
|
||||
=== Custom HTTP tracing
|
||||
To customize the items that are included in each trace, use the configprop:management.trace.http.include[] configuration property.
|
||||
For advanced customization, consider registering your own `HttpExchangeTracer` implementation.
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
[[actuator.whats-next]]
|
||||
== What to Read Next
|
||||
You might want to read about graphing tools such as https://graphiteapp.org[Graphite].
|
||||
|
||||
Otherwise, you can continue on, to read about <<deployment#deployment, '`deployment options`'>> or jump ahead for some in-depth information about Spring Boot's _<<build-tool-plugins#build-tool-plugins, build tool plugins>>_.
|
||||
|
|
@ -173,7 +173,7 @@ getting-started.first-application.executable-jar
|
|||
|
||||
# 2 == What to Read Next
|
||||
getting-started-whats-next=\
|
||||
getting-started.whats=next
|
||||
getting-started.whats-next
|
||||
|
||||
|
||||
|
||||
|
|
@ -2856,252 +2856,252 @@ howto.testcontainers
|
|||
# (appendix-application-properties.adoc)
|
||||
# 1 = Common Application properties
|
||||
common-application-properties=\
|
||||
appendix.common-application-properties
|
||||
application-properties
|
||||
|
||||
# 2 == Core Properties [[core-properties]]
|
||||
common-application-properties-core=\
|
||||
appendix.common-application-properties.core
|
||||
application-properties.core
|
||||
|
||||
# 2 == Cache Properties [[cache-properties]]
|
||||
common-application-properties-cache=\
|
||||
appendix.common-application-properties.cache
|
||||
application-properties.cache
|
||||
|
||||
# 2 == Mail Properties [[mail-properties]]
|
||||
common-application-properties-mail=\
|
||||
appendix.common-application-properties.mail
|
||||
application-properties.mail
|
||||
|
||||
# 2 == JSON Properties [[json-properties]]
|
||||
common-application-properties-json=\
|
||||
appendix.common-application-properties.json
|
||||
application-properties.json
|
||||
|
||||
# 2 == Data Properties [[data-properties]]
|
||||
common-application-properties-data=\
|
||||
appendix.common-application-properties.data
|
||||
application-properties.data
|
||||
|
||||
# 2 == Transaction Properties [[transaction-properties]]
|
||||
common-application-properties-transaction=\
|
||||
appendix.common-application-properties.transaction
|
||||
application-properties.transaction
|
||||
|
||||
# 2 == Data Migration Properties [[data-migration-properties]]
|
||||
common-application-properties-data-migration=\
|
||||
appendix.common-application-properties.data-migration
|
||||
application-properties.data-migration
|
||||
|
||||
# 2 == Integration Properties [[integration-properties]]
|
||||
common-application-properties-integration=\
|
||||
appendix.common-application-properties.integration
|
||||
application-properties.integration
|
||||
|
||||
# 2 == Web Properties [[web-properties]]
|
||||
common-application-properties-web=\
|
||||
appendix.common-application-properties.web
|
||||
application-properties.web
|
||||
|
||||
# 2 == Templating Properties [[templating-properties]]
|
||||
common-application-properties-templating=\
|
||||
appendix.common-application-properties.templating
|
||||
application-properties.templating
|
||||
|
||||
# 2 == Server Properties [[server-properties]]
|
||||
common-application-properties-server=\
|
||||
appendix.common-application-properties.server
|
||||
application-properties.server
|
||||
|
||||
# 2 == Security Properties [[security-properties]]
|
||||
common-application-properties-security=\
|
||||
appendix.common-application-properties.security
|
||||
application-properties.security
|
||||
|
||||
# 2 == RSocket Properties [[rsocket-properties]]
|
||||
common-application-properties-rsocket=\
|
||||
appendix.common-application-properties.rsocket
|
||||
application-properties.rsocket
|
||||
|
||||
# 2 == Actuator Properties [[actuator-properties]]
|
||||
common-application-properties-actuator=\
|
||||
appendix.common-application-properties.actuator
|
||||
application-properties.actuator
|
||||
|
||||
# 2 == Devtools Properties [[devtools-properties]]
|
||||
common-application-properties-devtools=\
|
||||
appendix.common-application-properties.devtools
|
||||
application-properties.devtools
|
||||
|
||||
# 2 == Testing Properties [[testing-properties]]
|
||||
common-application-properties-testing=\
|
||||
appendix.common-application-properties.testing
|
||||
application-properties.testing
|
||||
|
||||
|
||||
|
||||
# (configuration-metadata.adoc)
|
||||
# 1 = Configuration Metadata
|
||||
configuration-metadata=\
|
||||
appendix.configuration-metadata
|
||||
configuration-metadata
|
||||
|
||||
# 2 == Metadata Format
|
||||
configuration-metadata-format=\
|
||||
appendix.configuration-metadata.format
|
||||
configuration-metadata.format
|
||||
|
||||
# 3 === Group Attributes
|
||||
configuration-metadata-group-attributes=\
|
||||
appendix.configuration-metadata.format.group
|
||||
configuration-metadata.format.group
|
||||
|
||||
# 3 === Property Attributes
|
||||
configuration-metadata-property-attributes=\
|
||||
appendix.configuration-metadata.format.property
|
||||
configuration-metadata.format.property
|
||||
|
||||
# 3 === Hint Attributes
|
||||
configuration-metadata-hints-attributes=\
|
||||
appendix.configuration-metadata.format.hints
|
||||
configuration-metadata.format.hints
|
||||
|
||||
# 3 === Repeated Metadata Items
|
||||
configuration-metadata-repeated-items=\
|
||||
appendix.configuration-metadata.format.repeated-items
|
||||
configuration-metadata.format.repeated-items
|
||||
|
||||
# 2 == Providing Manual Hints
|
||||
configuration-metadata-providing-manual-hints=\
|
||||
appendix.configuration-metadata.manual-hints
|
||||
configuration-metadata.manual-hints
|
||||
|
||||
# 3 === Value Hint
|
||||
configuration-metadata-providing-manual-hints-value-hint=\
|
||||
appendix.configuration-metadata.manual-hints.value-hint
|
||||
configuration-metadata.manual-hints.value-hint
|
||||
|
||||
# 3 === Value Providers
|
||||
configuration-metadata-providing-manual-hints-value-providers=\
|
||||
appendix.configuration-metadata.manual-hints.value-providers
|
||||
configuration-metadata.manual-hints.value-providers
|
||||
|
||||
# 4 ==== Any
|
||||
configuration-metadata-providing-manual-hints-any=\
|
||||
appendix.configuration-metadata.manual-hints.value-providers.any
|
||||
configuration-metadata.manual-hints.value-providers.any
|
||||
|
||||
# 4 ==== Class Reference
|
||||
configuration-metadata-providing-manual-hints-class-reference=\
|
||||
appendix.configuration-metadata.manual-hints.value-providers.class-reference
|
||||
configuration-metadata.manual-hints.value-providers.class-reference
|
||||
|
||||
# 4 ==== Handle As
|
||||
configuration-metadata-providing-manual-hints-handle-as=\
|
||||
appendix.configuration-metadata.manual-hints.value-providers.handle-as
|
||||
configuration-metadata.manual-hints.value-providers.handle-as
|
||||
|
||||
# 4 ==== Logger Name
|
||||
configuration-metadata-providing-manual-hints-logger-name=\
|
||||
appendix.configuration-metadata.manual-hints.value-providers.logger-name
|
||||
configuration-metadata.manual-hints.value-providers.logger-name
|
||||
|
||||
# 4 ==== Spring Bean Reference
|
||||
configuration-metadata-providing-manual-hints-spring-bean-reference=\
|
||||
appendix.configuration-metadata.manual-hints.value-providers.spring-bean-reference
|
||||
configuration-metadata.manual-hints.value-providers.spring-bean-reference
|
||||
|
||||
# 4 ==== Spring Profile Name
|
||||
configuration-metadata-providing-manual-hints-spring-profile-name=\
|
||||
appendix.configuration-metadata.manual-hints.value-providers.spring-profile-name
|
||||
configuration-metadata.manual-hints.value-providers.spring-profile-name
|
||||
|
||||
# 2 == Generating Your Own Metadata by Using the Annotation Processor
|
||||
configuration-metadata-annotation-processor=\
|
||||
appendix.configuration-metadata.annotation-processor
|
||||
configuration-metadata.annotation-processor
|
||||
|
||||
# 3 === Configuring the Annotation Processor
|
||||
configuration-metadata-annotation-processor-setup=\
|
||||
appendix.configuration-metadata.annotation-processor.configuring
|
||||
configuration-metadata.annotation-processor.configuring
|
||||
|
||||
# 3 === Automatic Metadata Generation
|
||||
configuration-metadata-annotation-processor-metadata-generation=\
|
||||
appendix.configuration-metadata.annotation-processor.automatic-metadata-generation
|
||||
configuration-metadata.annotation-processor.automatic-metadata-generation
|
||||
|
||||
# 4 ==== Nested Properties
|
||||
configuration-metadata-annotation-processor-metadata-generation-nested=\
|
||||
appendix.configuration-metadata.annotation-processor.automatic-metadata-generation.nested-properties
|
||||
configuration-metadata.annotation-processor.automatic-metadata-generation.nested-properties
|
||||
|
||||
# 3 === Adding Additional Metadata
|
||||
configuration-metadata-additional-metadata=\
|
||||
appendix.configuration-metadata.annotation-processor.adding-additional-metadata
|
||||
configuration-metadata.annotation-processor.adding-additional-metadata
|
||||
|
||||
|
||||
|
||||
# (auto-configuration-classes.adoc)
|
||||
# 1 = Auto-configuration Classes
|
||||
auto-configuration-classes=\
|
||||
appendix.auto-configuration-classes
|
||||
auto-configuration-classes
|
||||
|
||||
# 2 == spring-boot-autoconfigure
|
||||
auto-configuration-classes-from-autoconfigure-module=\
|
||||
appendix.auto-configuration-classes.core
|
||||
auto-configuration-classes.core
|
||||
|
||||
# 2 == spring-boot-actuator-autoconfigure
|
||||
auto-configuration-classes-from-actuator=\
|
||||
appendix.auto-configuration-classes.actuator
|
||||
auto-configuration-classes.actuator
|
||||
|
||||
|
||||
|
||||
# (test-auto-configuration.adoc)
|
||||
# 1 = Test Auto-configuration Annotations
|
||||
test-auto-configuration=\
|
||||
appendix.test-auto-configuration
|
||||
test-auto-configuration
|
||||
|
||||
# 2 == Test Slices
|
||||
test-auto-configuration-slices=\
|
||||
appendix.test-auto-configuration.slices
|
||||
test-auto-configuration.slices
|
||||
|
||||
|
||||
|
||||
# (executable-jar.adoc)
|
||||
# 1 = The Executable Jar Format
|
||||
executable-jar=\
|
||||
appendix.executable-jar
|
||||
executable-jar
|
||||
|
||||
# 2 == Nested JARs
|
||||
executable-jar-nested-jars=\
|
||||
appendix.executable-jar.nested-jars
|
||||
executable-jar.nested-jars
|
||||
|
||||
# 3 === The Executable Jar File Structure
|
||||
executable-jar-jar-file-structure=\
|
||||
appendix.executable-jar.nested-jars.jar-structure
|
||||
executable-jar.nested-jars.jar-structure
|
||||
|
||||
# 3 === The Executable War File Structure
|
||||
executable-jar-war-file-structure=\
|
||||
appendix.executable-jar.nested-jars.war-structure
|
||||
executable-jar.nested-jars.war-structure
|
||||
|
||||
# 3 === Index Files
|
||||
executable-jar-war-index-files=\
|
||||
appendix.executable-jar.nested-jars.index-files
|
||||
executable-jar.nested-jars.index-files
|
||||
|
||||
# 3 === Classpath Index
|
||||
executable-jar-war-index-files-classpath=\
|
||||
appendix.executable-jar.nested-jars.classpath-index
|
||||
executable-jar.nested-jars.classpath-index
|
||||
|
||||
# 3 === Layer Index
|
||||
executable-jar-war-index-files-layers=\
|
||||
appendix.executable-jar.nested-jars.layer-index
|
||||
executable-jar.nested-jars.layer-index
|
||||
|
||||
# 2 == Spring Boot's "`JarFile`" Class
|
||||
executable-jar-jarfile=\
|
||||
appendix.executable-jar.jarfile-class
|
||||
executable-jar.jarfile-class
|
||||
|
||||
# 3 === Compatibility with the Standard Java "`JarFile`"
|
||||
executable-jar-jarfile-compatibility=\
|
||||
appendix.executable-jar.jarfile-class.compatibilty
|
||||
executable-jar.jarfile-class.compatibilty
|
||||
|
||||
# 2 == Launching Executable Jars
|
||||
executable-jar-launching=\
|
||||
appendix.executable-jar.launching
|
||||
executable-jar.launching
|
||||
|
||||
# 3 === Launcher Manifest
|
||||
executable-jar-launcher-manifest=\
|
||||
appendix.executable-jar.launching.manifest
|
||||
executable-jar.launching.manifest
|
||||
|
||||
# 2 == PropertiesLauncher Features
|
||||
executable-jar-property-launcher-features=\
|
||||
appendix.executable-jar.property-launcher
|
||||
executable-jar.property-launcher
|
||||
|
||||
# 2 == Executable Jar Restrictions
|
||||
executable-jar-restrictions=\
|
||||
appendix.executable-jar.restrictions
|
||||
executable-jar.restrictions
|
||||
|
||||
# 2 == Alternative Single Jar Solutions
|
||||
executable-jar-alternatives=\
|
||||
appendix.executable-jar.alternatives
|
||||
executable-jar.alternatives
|
||||
|
||||
|
||||
|
||||
# (dependency-versions.adoc)
|
||||
# 1 = Dependency versions
|
||||
dependency-versions=\
|
||||
appendix.dependency-versions
|
||||
dependency-versions
|
||||
|
||||
# 2 == Managed Dependency Coordinates
|
||||
dependency-versions-coordinates=\
|
||||
appendix.dependency-versions.coordinates
|
||||
dependency-versions.coordinates
|
||||
|
||||
# 2 == Version Properties
|
||||
dependency-versions-properties=\
|
||||
appendix.dependency-versions.properties
|
||||
dependency-versions.properties
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,48 @@
|
|||
[appendix]
|
||||
[[application-properties]]
|
||||
= Common Application properties
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
|
||||
This appendix provides a list of common 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 <<features#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.
|
||||
Also, you can define your own properties.
|
||||
|
||||
|
||||
|
||||
include::application-properties/core.adoc[]
|
||||
|
||||
include::application-properties/cache.adoc[]
|
||||
|
||||
include::application-properties/mail.adoc[]
|
||||
|
||||
include::application-properties/json.adoc[]
|
||||
|
||||
include::application-properties/data.adoc[]
|
||||
|
||||
include::application-properties/transaction.adoc[]
|
||||
|
||||
include::application-properties/data-migration.adoc[]
|
||||
|
||||
include::application-properties/integration.adoc[]
|
||||
|
||||
include::application-properties/web.adoc[]
|
||||
|
||||
include::application-properties/templating.adoc[]
|
||||
|
||||
include::application-properties/server.adoc[]
|
||||
|
||||
include::application-properties/security.adoc[]
|
||||
|
||||
include::application-properties/rsocket.adoc[]
|
||||
|
||||
include::application-properties/actuator.adoc[]
|
||||
|
||||
include::application-properties/devtools.adoc[]
|
||||
|
||||
include::application-properties/testing.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.actuator]]
|
||||
== Actuator Properties [[actuator-properties]]
|
||||
include::documented-application-properties/actuator.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.cache]]
|
||||
== Cache Properties [[cache-properties]]
|
||||
include::documented-application-properties/cache.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.core]]
|
||||
== Core Properties [[core-properties]]
|
||||
include::documented-application-properties/core.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.data-migration]]
|
||||
== Data Migration Properties [[data-migration-properties]]
|
||||
include::documented-application-properties/data-migration.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.data]]
|
||||
== Data Properties [[data-properties]]
|
||||
include::documented-application-properties/data.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.devtools]]
|
||||
== Devtools Properties [[devtools-properties]]
|
||||
include::documented-application-properties/devtools.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.integration]]
|
||||
== Integration Properties [[integration-properties]]
|
||||
include::documented-application-properties/integration.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.json]]
|
||||
== JSON Properties [[json-properties]]
|
||||
include::documented-application-properties/json.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.mail]]
|
||||
== Mail Properties [[mail-properties]]
|
||||
include::documented-application-properties/mail.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.rsocket]]
|
||||
== RSocket Properties [[rsocket-properties]]
|
||||
include::documented-application-properties/rsocket.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.security]]
|
||||
== Security Properties [[security-properties]]
|
||||
include::documented-application-properties/security.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.server]]
|
||||
== Server Properties [[server-properties]]
|
||||
include::documented-application-properties/server.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.templating]]
|
||||
== Templating Properties [[templating-properties]]
|
||||
include::documented-application-properties/templating.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.testing]]
|
||||
== Testing Properties [[testing-properties]]
|
||||
include::documented-application-properties/testing.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.transaction]]
|
||||
== Transaction Properties [[transaction-properties]]
|
||||
include::documented-application-properties/transaction.adoc[]
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
[[application-properties.web]]
|
||||
== Web Properties [[web-properties]]
|
||||
include::documented-application-properties/web.adoc[]
|
||||
|
|
@ -10,21 +10,17 @@
|
|||
:hide-uri-scheme:
|
||||
:docinfo: shared,private
|
||||
:chomp: tags formatters headers packages
|
||||
|
||||
:spring-boot-artifactory-repo: snapshot
|
||||
:github-tag: main
|
||||
:spring-boot-version: current
|
||||
|
||||
:github-repo: spring-projects/spring-boot
|
||||
:github-raw: https://raw.githubusercontent.com/{github-repo}/{github-tag}
|
||||
:github-issues: https://github.com/{github-repo}/issues/
|
||||
:github-wiki: https://github.com/{github-repo}/wiki
|
||||
|
||||
:include: ../main/java/org/springframework/boot/docs
|
||||
:include: ../../main/java/org/springframework/boot/docs
|
||||
:include-springbootfeatures: {include}/springbootfeatures
|
||||
:include-productionreadyfeatures: {include}/productionreadyfeatures
|
||||
:include-howto: {include}/howto
|
||||
|
||||
:spring-boot-code: https://github.com/{github-repo}/tree/{github-tag}
|
||||
:spring-boot-api: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/api
|
||||
:spring-boot-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/reference
|
||||
|
|
@ -38,7 +34,6 @@
|
|||
:spring-boot-gradle-plugin-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/gradle-plugin/reference/htmlsingle/
|
||||
:spring-boot-gradle-plugin-pdfdocs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/gradle-plugin/reference/pdf/spring-boot-gradle-plugin-reference.pdf
|
||||
:spring-boot-gradle-plugin-api: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/gradle-plugin/api/
|
||||
|
||||
:spring-boot-module-code: {spring-boot-code}/spring-boot-project/spring-boot/src/main/java/org/springframework/boot
|
||||
:spring-boot-module-api: {spring-boot-api}/org/springframework/boot
|
||||
:spring-boot-autoconfigure-module-code: {spring-boot-code}/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure
|
||||
|
|
@ -55,7 +50,6 @@
|
|||
:spring-boot-test-module-api: {spring-boot-api}/org/springframework/boot/test
|
||||
:spring-boot-test-autoconfigure-module-code: {spring-boot-code}/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure
|
||||
:spring-boot-test-autoconfigure-module-api: {spring-boot-api}/org/springframework/boot/test/autoconfigure
|
||||
|
||||
:spring-amqp-api: https://docs.spring.io/spring-amqp/docs/{spring-amqp-version}/api/org/springframework/amqp
|
||||
:spring-batch: https://spring.io/projects/spring-batch
|
||||
:spring-batch-api: https://docs.spring.io/spring-batch/docs/{spring-batch-version}/api/org/springframework/batch
|
||||
|
|
@ -94,7 +88,6 @@
|
|||
:spring-security-oauth2-docs: https://projects.spring.io/spring-security-oauth/docs/oauth2.html
|
||||
:spring-session: https://spring.io/projects/spring-session
|
||||
:spring-webservices-docs: https://docs.spring.io/spring-ws/docs/{spring-webservices-version}/reference/
|
||||
|
||||
:ant-docs: https://ant.apache.org/manual
|
||||
:dependency-management-plugin-code: https://github.com/spring-gradle-plugins/dependency-management-plugin
|
||||
:gradle-docs: https://docs.gradle.org/current/userguide
|
||||
|
|
|
|||
|
|
@ -1,24 +1,16 @@
|
|||
[appendix]
|
||||
[[appendix.auto-configuration-classes]]
|
||||
[[auto-configuration-classes]]
|
||||
= Auto-configuration Classes
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
This appendix contains details of all of the auto-configuration classes provided by Spring Boot, with links to documentation and source code.
|
||||
Remember to also look at the conditions report in your application for more details of which features are switched on.
|
||||
(To do so, start the app with `--debug` or `-Ddebug` or, in an Actuator application, use the `conditions` endpoint).
|
||||
|
||||
|
||||
|
||||
[[appendix.auto-configuration-classes.core]]
|
||||
== spring-boot-autoconfigure
|
||||
The following auto-configuration classes are from the `spring-boot-autoconfigure` module:
|
||||
include::auto-configuration-classes/core.adoc[]
|
||||
|
||||
include::auto-configuration-classes/spring-boot-autoconfigure.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.auto-configuration-classes.actuator]]
|
||||
== spring-boot-actuator-autoconfigure
|
||||
The following auto-configuration classes are from the `spring-boot-actuator-autoconfigure` module:
|
||||
|
||||
include::auto-configuration-classes/spring-boot-actuator-autoconfigure.adoc[]
|
||||
include::auto-configuration-classes/actuator.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
[[auto-configuration-classes.actuator]]
|
||||
== spring-boot-actuator-autoconfigure
|
||||
The following auto-configuration classes are from the `spring-boot-actuator-autoconfigure` module:
|
||||
|
||||
include::documented-auto-configuration-classes/spring-boot-actuator-autoconfigure.adoc[]
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
[[auto-configuration-classes.core]]
|
||||
== spring-boot-autoconfigure
|
||||
The following auto-configuration classes are from the `spring-boot-autoconfigure` module:
|
||||
|
||||
include::documented-auto-configuration-classes/spring-boot-autoconfigure.adoc[]
|
||||
|
|
@ -2,244 +2,21 @@
|
|||
= Build Tool Plugins
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
Spring Boot provides build tool plugins for Maven and Gradle.
|
||||
The plugins offer a variety of features, including the packaging of executable jars.
|
||||
This section provides more details on both plugins as well as some help should you need to extend an unsupported build system.
|
||||
If you are just getting started, you might want to read "`<<using.adoc#using.build-systems>>`" from the "`<<using.adoc#using>>`" section first.
|
||||
If you are just getting started, you might want to read "`<<using#using.build-systems>>`" from the "`<<using#using>>`" section first.
|
||||
|
||||
|
||||
|
||||
[[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).
|
||||
include::build-tool-plugins/maven.adoc[]
|
||||
|
||||
Please refer to the plugin's documentation to learn more:
|
||||
include::build-tool-plugins/gradle.adoc[]
|
||||
|
||||
* Reference ({spring-boot-maven-plugin-docs}[HTML] and {spring-boot-maven-plugin-pdfdocs}[PDF])
|
||||
* {spring-boot-maven-plugin-api}[API]
|
||||
include::build-tool-plugins/antlib.adoc[]
|
||||
|
||||
include::build-tool-plugins/other-build-systems.adoc[]
|
||||
|
||||
|
||||
[[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.
|
||||
Please refer to the plugin's documentation to learn more:
|
||||
|
||||
* Reference ({spring-boot-gradle-plugin-docs}[HTML] and {spring-boot-gradle-plugin-pdfdocs}[PDF])
|
||||
* {spring-boot-gradle-plugin-api}[API]
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
To use the module, you need to declare an additional `spring-boot` namespace in your `build.xml`, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<project xmlns:ivy="antlib:org.apache.ivy.ant"
|
||||
xmlns:spring-boot="antlib:org.springframework.boot.ant"
|
||||
name="myapp" default="build">
|
||||
...
|
||||
</project>
|
||||
----
|
||||
|
||||
You need to remember to start Ant using the `-lib` option, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ ant -lib <directory containing spring-boot-antlib-{spring-boot-version}.jar>
|
||||
----
|
||||
|
||||
TIP: The "`Using Spring Boot`" section includes a more complete example of <<using.adoc#using.build-systems.ant, using Apache Ant with `spring-boot-antlib`>>.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.tasks]]
|
||||
=== Spring Boot Ant Tasks
|
||||
Once the `spring-boot-antlib` namespace has been declared, the following additional tasks are available:
|
||||
|
||||
* <<build-tool-plugins.antlib.tasks.exejar>>
|
||||
* <<build-tool-plugins.antlib.findmainclass>>
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[cols="1,2,2"]
|
||||
|====
|
||||
| Attribute | Description | Required
|
||||
|
||||
| `destfile`
|
||||
| The destination jar file to create
|
||||
| Yes
|
||||
|
||||
| `classes`
|
||||
| The root directory of Java class files
|
||||
| Yes
|
||||
|
||||
| `start-class`
|
||||
| The main application class to run
|
||||
| No _(the default is the first class found that declares a `main` method)_
|
||||
|====
|
||||
|
||||
The following nested elements can be used with the task:
|
||||
|
||||
[cols="1,4"]
|
||||
|====
|
||||
| Element | Description
|
||||
|
||||
| `resources`
|
||||
| One or more {ant-docs}/Types/resources.html#collection[Resource Collections] describing a set of {ant-docs}/Types/resources.html[Resources] that should be added to the content of the created +jar+ file.
|
||||
|
||||
| `lib`
|
||||
| One or more {ant-docs}/Types/resources.html#collection[Resource Collections] that should be added to the set of jar libraries that make up the runtime dependency classpath of the application.
|
||||
|====
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.tasks.examples]]
|
||||
==== Examples
|
||||
This section shows two examples of Ant tasks.
|
||||
|
||||
.Specify +start-class+
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<spring-boot:exejar destfile="target/my-application.jar"
|
||||
classes="target/classes" start-class="com.example.MyApplication">
|
||||
<resources>
|
||||
<fileset dir="src/main/resources" />
|
||||
</resources>
|
||||
<lib>
|
||||
<fileset dir="lib" />
|
||||
</lib>
|
||||
</spring-boot:exejar>
|
||||
----
|
||||
|
||||
.Detect +start-class+
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<exejar destfile="target/my-application.jar" classes="target/classes">
|
||||
<lib>
|
||||
<fileset dir="lib" />
|
||||
</lib>
|
||||
</exejar>
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
The following attributes are supported:
|
||||
|
||||
[cols="1,2,2"]
|
||||
|====
|
||||
| Attribute | Description | Required
|
||||
|
||||
| `classesroot`
|
||||
| The root directory of Java class files
|
||||
| Yes _(unless `mainclass` is specified)_
|
||||
|
||||
| `mainclass`
|
||||
| Can be used to short-circuit the `main` class search
|
||||
| No
|
||||
|
||||
| `property`
|
||||
| The Ant property that should be set with the result
|
||||
| No _(result will be logged if unspecified)_
|
||||
|====
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.findmainclass.examples]]
|
||||
==== Examples
|
||||
This section contains three examples of using `findmainclass`.
|
||||
|
||||
.Find and log
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<findmainclass classesroot="target/classes" />
|
||||
----
|
||||
|
||||
.Find and set
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<findmainclass classesroot="target/classes" property="main-class" />
|
||||
----
|
||||
|
||||
.Override and set
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<findmainclass mainclass="com.example.MainClass" property="main-class" />
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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 "`<<executable-jar.adoc#appendix.executable-jar, executable jar format>>`" section in the appendix for details).
|
||||
|
||||
The Spring Boot Maven and Gradle plugins both make use of `spring-boot-loader-tools` to actually generate jars.
|
||||
If you need to, you may use this library directly.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.other-build-systems.repackaging-archives]]
|
||||
=== Repackaging Archives
|
||||
To repackage an existing archive so that it becomes a self-contained executable archive, use `org.springframework.boot.loader.tools.Repackager`.
|
||||
The `Repackager` class takes a single constructor argument that refers to an existing jar or war archive.
|
||||
Use one of the two available `repackage()` methods to either replace the original file or write to a new destination.
|
||||
Various settings can also be configured on the repackager before it is run.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.other-build-systems.nested-libraries]]
|
||||
=== Nested Libraries
|
||||
When repackaging an archive, you can include references to dependency files by using the `org.springframework.boot.loader.tools.Libraries` interface.
|
||||
We do not provide any concrete implementations of `Libraries` here as they are usually build-system-specific.
|
||||
|
||||
If your archive already includes libraries, you can use `Libraries.NONE`.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.other-build-systems.finding-main-class]]
|
||||
=== Finding a Main Class
|
||||
If you do not use `Repackager.setMainClass()` to specify a main class, the repackager uses https://asm.ow2.io/[ASM] to read class files and tries to find a suitable class with a `public static void main(String[] args)` method.
|
||||
An exception is thrown if more than one candidate is found.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.other-build-systems.example-repackage-implementation]]
|
||||
=== Example Repackage Implementation
|
||||
The following example shows a typical repackage implementation:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
Repackager repackager = new Repackager(sourceJarFile);
|
||||
repackager.setBackupSource(false);
|
||||
repackager.repackage(new Libraries() {
|
||||
@Override
|
||||
public void doWithLibraries(LibraryCallback callback) throws IOException {
|
||||
// Build system specific implementation, callback for each dependency
|
||||
// callback.library(new Library(nestedFile, LibraryScope.COMPILE));
|
||||
}
|
||||
});
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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#appendix.executable-jar,the appendix>>.
|
||||
|
||||
If you have specific build-related questions, you can check out the "`<<howto.adoc#howto, how-to>>`" guides.
|
||||
include::build-tool-plugins/whats-next.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,148 @@
|
|||
[[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.
|
||||
To use the module, you need to declare an additional `spring-boot` namespace in your `build.xml`, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<project xmlns:ivy="antlib:org.apache.ivy.ant"
|
||||
xmlns:spring-boot="antlib:org.springframework.boot.ant"
|
||||
name="myapp" default="build">
|
||||
...
|
||||
</project>
|
||||
----
|
||||
|
||||
You need to remember to start Ant using the `-lib` option, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ ant -lib <directory containing spring-boot-antlib-{spring-boot-version}.jar>
|
||||
----
|
||||
|
||||
TIP: The "`Using Spring Boot`" section includes a more complete example of <<using#using.build-systems.ant, using Apache Ant with `spring-boot-antlib`>>.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.tasks]]
|
||||
=== Spring Boot Ant Tasks
|
||||
Once the `spring-boot-antlib` namespace has been declared, the following additional tasks are available:
|
||||
|
||||
* <<build-tool-plugins#build-tool-plugins.antlib.tasks.exejar>>
|
||||
* <<build-tool-plugins#build-tool-plugins.antlib.findmainclass>>
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[cols="1,2,2"]
|
||||
|====
|
||||
| Attribute | Description | Required
|
||||
|
||||
| `destfile`
|
||||
| The destination jar file to create
|
||||
| Yes
|
||||
|
||||
| `classes`
|
||||
| The root directory of Java class files
|
||||
| Yes
|
||||
|
||||
| `start-class`
|
||||
| The main application class to run
|
||||
| No _(the default is the first class found that declares a `main` method)_
|
||||
|====
|
||||
|
||||
The following nested elements can be used with the task:
|
||||
|
||||
[cols="1,4"]
|
||||
|====
|
||||
| Element | Description
|
||||
|
||||
| `resources`
|
||||
| One or more {ant-docs}/Types/resources.html#collection[Resource Collections] describing a set of {ant-docs}/Types/resources.html[Resources] that should be added to the content of the created +jar+ file.
|
||||
|
||||
| `lib`
|
||||
| One or more {ant-docs}/Types/resources.html#collection[Resource Collections] that should be added to the set of jar libraries that make up the runtime dependency classpath of the application.
|
||||
|====
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.tasks.examples]]
|
||||
==== Examples
|
||||
This section shows two examples of Ant tasks.
|
||||
|
||||
.Specify +start-class+
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<spring-boot:exejar destfile="target/my-application.jar"
|
||||
classes="target/classes" start-class="com.example.MyApplication">
|
||||
<resources>
|
||||
<fileset dir="src/main/resources" />
|
||||
</resources>
|
||||
<lib>
|
||||
<fileset dir="lib" />
|
||||
</lib>
|
||||
</spring-boot:exejar>
|
||||
----
|
||||
|
||||
.Detect +start-class+
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<exejar destfile="target/my-application.jar" classes="target/classes">
|
||||
<lib>
|
||||
<fileset dir="lib" />
|
||||
</lib>
|
||||
</exejar>
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
The following attributes are supported:
|
||||
|
||||
[cols="1,2,2"]
|
||||
|====
|
||||
| Attribute | Description | Required
|
||||
|
||||
| `classesroot`
|
||||
| The root directory of Java class files
|
||||
| Yes _(unless `mainclass` is specified)_
|
||||
|
||||
| `mainclass`
|
||||
| Can be used to short-circuit the `main` class search
|
||||
| No
|
||||
|
||||
| `property`
|
||||
| The Ant property that should be set with the result
|
||||
| No _(result will be logged if unspecified)_
|
||||
|====
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.findmainclass.examples]]
|
||||
==== Examples
|
||||
This section contains three examples of using `findmainclass`.
|
||||
|
||||
.Find and log
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<findmainclass classesroot="target/classes" />
|
||||
----
|
||||
|
||||
.Find and set
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<findmainclass classesroot="target/classes" property="main-class" />
|
||||
----
|
||||
|
||||
.Override and set
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<findmainclass mainclass="com.example.MainClass" property="main-class" />
|
||||
----
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
[[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.
|
||||
Please refer to the plugin's documentation to learn more:
|
||||
|
||||
* Reference ({spring-boot-gradle-plugin-docs}[HTML] and {spring-boot-gradle-plugin-pdfdocs}[PDF])
|
||||
* {spring-boot-gradle-plugin-api}[API]
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
[[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).
|
||||
|
||||
Please refer to the plugin's documentation to learn more:
|
||||
|
||||
* Reference ({spring-boot-maven-plugin-docs}[HTML] and {spring-boot-maven-plugin-pdfdocs}[PDF])
|
||||
* {spring-boot-maven-plugin-api}[API]
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
[[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 "`<<executable-jar#executable-jar, executable jar format>>`" section in the appendix for details).
|
||||
|
||||
The Spring Boot Maven and Gradle plugins both make use of `spring-boot-loader-tools` to actually generate jars.
|
||||
If you need to, you may use this library directly.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.other-build-systems.repackaging-archives]]
|
||||
=== Repackaging Archives
|
||||
To repackage an existing archive so that it becomes a self-contained executable archive, use `org.springframework.boot.loader.tools.Repackager`.
|
||||
The `Repackager` class takes a single constructor argument that refers to an existing jar or war archive.
|
||||
Use one of the two available `repackage()` methods to either replace the original file or write to a new destination.
|
||||
Various settings can also be configured on the repackager before it is run.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.other-build-systems.nested-libraries]]
|
||||
=== Nested Libraries
|
||||
When repackaging an archive, you can include references to dependency files by using the `org.springframework.boot.loader.tools.Libraries` interface.
|
||||
We do not provide any concrete implementations of `Libraries` here as they are usually build-system-specific.
|
||||
|
||||
If your archive already includes libraries, you can use `Libraries.NONE`.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.other-build-systems.finding-main-class]]
|
||||
=== Finding a Main Class
|
||||
If you do not use `Repackager.setMainClass()` to specify a main class, the repackager uses https://asm.ow2.io/[ASM] to read class files and tries to find a suitable class with a `public static void main(String[] args)` method.
|
||||
An exception is thrown if more than one candidate is found.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.other-build-systems.example-repackage-implementation]]
|
||||
=== Example Repackage Implementation
|
||||
The following example shows a typical repackage implementation:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
Repackager repackager = new Repackager(sourceJarFile);
|
||||
repackager.setBackupSource(false);
|
||||
repackager.repackage(new Libraries() {
|
||||
@Override
|
||||
public void doWithLibraries(LibraryCallback callback) throws IOException {
|
||||
// Build system specific implementation, callback for each dependency
|
||||
// callback.library(new Library(nestedFile, LibraryScope.COMPILE));
|
||||
}
|
||||
});
|
||||
----
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
[[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 <<executable-jar#executable-jar,the appendix>>.
|
||||
|
||||
If you have specific build-related questions, you can check out the "`<<howto#howto, how-to>>`" guides.
|
||||
|
|
@ -2,434 +2,19 @@
|
|||
= Spring Boot CLI
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
The Spring Boot CLI is a command line tool that you can use if you want to quickly develop a Spring application.
|
||||
It lets you run Groovy scripts, which means that you have a familiar Java-like syntax without so much boilerplate code.
|
||||
You can also bootstrap a new project or write your own command for it.
|
||||
|
||||
|
||||
|
||||
[[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.cli>>_ in the "`Getting started`" section for comprehensive installation instructions.
|
||||
include::cli/installation.adoc[]
|
||||
|
||||
include::cli/using-the-cli.adoc[]
|
||||
|
||||
include::cli/groovy-beans-dsl.adoc[]
|
||||
|
||||
[[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:
|
||||
include::cli/maven-setting.adoc[]
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring
|
||||
usage: spring [--help] [--version]
|
||||
<command> [<args>]
|
||||
|
||||
Available commands are:
|
||||
|
||||
run [options] <files> [--] [args]
|
||||
Run a spring groovy script
|
||||
|
||||
_... more command help is shown here_
|
||||
----
|
||||
|
||||
You can type `spring help` to get more details about any of the supported commands, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring help run
|
||||
spring run - Run a spring groovy script
|
||||
|
||||
usage: spring run [options] <files> [--] [args]
|
||||
|
||||
Option Description
|
||||
------ -----------
|
||||
--autoconfigure [Boolean] Add autoconfigure compiler
|
||||
transformations (default: true)
|
||||
--classpath, -cp Additional classpath entries
|
||||
--no-guess-dependencies Do not attempt to guess dependencies
|
||||
--no-guess-imports Do not attempt to guess imports
|
||||
-q, --quiet Quiet logging
|
||||
-v, --verbose Verbose logging of dependency
|
||||
resolution
|
||||
--watch Watch the specified file for changes
|
||||
----
|
||||
|
||||
The `version` command provides a quick way to check which version of Spring Boot you are using, as follows:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring version
|
||||
Spring CLI v{spring-boot-version}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
The following example shows a "`hello world`" web application written in Groovy:
|
||||
|
||||
.hello.groovy
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@RestController
|
||||
class WebApplication {
|
||||
|
||||
@RequestMapping("/")
|
||||
String home() {
|
||||
"Hello World!"
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
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 `--` to separate the commands from the "`spring`" command arguments, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring run hello.groovy -- --server.port=9000
|
||||
----
|
||||
|
||||
To set JVM command line arguments, you can use the `JAVA_OPTS` environment variable, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ JAVA_OPTS=-Xmx1024m spring run hello.groovy
|
||||
----
|
||||
|
||||
NOTE: When setting `JAVA_OPTS` on Microsoft Windows, make sure to quote the entire instruction, such as `set "JAVA_OPTS=-Xms256m -Xmx2048m"`.
|
||||
Doing so ensures the values are properly passed to the process.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.deduced-grab-annotations]]
|
||||
==== Deduced "`grab`" Dependencies
|
||||
Standard Groovy includes a `@Grab` annotation, which lets you declare dependencies on third-party libraries.
|
||||
This useful technique lets Groovy download jars in the same way as Maven or Gradle would but without requiring you to use a build tool.
|
||||
|
||||
Spring Boot extends this technique further and tries to deduce which libraries to "`grab`" based on your code.
|
||||
For example, since the `WebApplication` code shown previously uses `@RestController` annotations, Spring Boot grabs "Tomcat" and "Spring MVC".
|
||||
|
||||
The following items are used as "`grab hints`":
|
||||
|
||||
|===
|
||||
| Items | Grabs
|
||||
|
||||
| `JdbcTemplate`, `NamedParameterJdbcTemplate`, `DataSource`
|
||||
| JDBC Application.
|
||||
|
||||
| `@EnableJms`
|
||||
| JMS Application.
|
||||
|
||||
| `@EnableCaching`
|
||||
| Caching abstraction.
|
||||
|
||||
| `@Test`
|
||||
| JUnit.
|
||||
|
||||
| `@EnableRabbit`
|
||||
| RabbitMQ.
|
||||
|
||||
| extends `Specification`
|
||||
| Spock test.
|
||||
|
||||
| `@EnableBatchProcessing`
|
||||
| Spring Batch.
|
||||
|
||||
| `@MessageEndpoint` `@EnableIntegration`
|
||||
| Spring Integration.
|
||||
|
||||
| `@Controller` `@RestController` `@EnableWebMvc`
|
||||
| Spring MVC + Embedded Tomcat.
|
||||
|
||||
| `@EnableWebSecurity`
|
||||
| Spring Security.
|
||||
|
||||
| `@EnableTransactionManagement`
|
||||
| Spring Transaction Management.
|
||||
|===
|
||||
|
||||
TIP: See subclasses of {spring-boot-cli-module-code}/compiler/CompilerAutoConfiguration.java[`CompilerAutoConfiguration`] in the Spring Boot CLI source code to understand exactly how customizations are applied.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.deduced-grab-coordinates]]
|
||||
==== Deduced "`grab`" Coordinates
|
||||
Spring Boot extends Groovy's standard `@Grab` support by letting you specify a dependency without a group or version (for example, `@Grab('freemarker')`).
|
||||
Doing so consults Spring Boot's default dependency metadata to deduce the artifact's group and version.
|
||||
|
||||
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 <<dependency-versions.adoc#appendix.dependency-versions,appendix>>.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.default-import-statements]]
|
||||
==== Default Import Statements
|
||||
To help reduce the size of your Groovy code, several `import` statements are automatically included.
|
||||
Notice how the preceding example refers to `@Component`, `@RestController`, and `@RequestMapping` without needing to use fully-qualified names or `import` statements.
|
||||
|
||||
TIP: Many Spring annotations work without using `import` statements.
|
||||
Try running your application to see what fails before adding imports.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.automatic-main-method]]
|
||||
==== Automatic Main Method
|
||||
Unlike the equivalent Java application, you do not need to include a `public static void main(String[] args)` method with your `Groovy` scripts.
|
||||
A `SpringApplication` is automatically created, with your compiled code acting as the `source`.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.custom-dependency-management]]
|
||||
==== Custom Dependency Management
|
||||
By default, the CLI uses the dependency management declared in `spring-boot-dependencies` when resolving `@Grab` dependencies.
|
||||
Additional dependency management, which overrides the default dependency management, can be configured by using the `@DependencyManagementBom` annotation.
|
||||
The annotation's value should specify the coordinates (`groupId:artifactId:version`) of one or more Maven BOMs.
|
||||
|
||||
For example, consider the following declaration:
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
@DependencyManagementBom("com.example.custom-bom:1.0.0")
|
||||
----
|
||||
|
||||
The preceding declaration picks up `custom-bom-1.0.0.pom` in a Maven repository under `com/example/custom-versions/1.0.0/`.
|
||||
|
||||
When you specify multiple BOMs, they are applied in the order in which you declare them, as shown in the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
@DependencyManagementBom(["com.example.custom-bom:1.0.0",
|
||||
"com.example.another-bom:1.0.0"])
|
||||
----
|
||||
|
||||
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 `@DependencyManagementBom` at most once in your application.
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring run *.groovy
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring jar my-app.jar *.groovy
|
||||
----
|
||||
|
||||
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 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]
|
||||
----
|
||||
public/**, resources/**, static/**, templates/**, META-INF/**, *
|
||||
----
|
||||
|
||||
The default excludes are as follows:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
.*, repository/**, build/**, target/**, **/*.jar, **/*.groovy
|
||||
----
|
||||
|
||||
Type `spring help jar` on the command line for more information.
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring init --dependencies=web,data-jpa my-project
|
||||
Using service at https://start.spring.io
|
||||
Project extracted to '/Users/developer/example/my-project'
|
||||
----
|
||||
|
||||
The preceding example creates a `my-project` directory with a Maven-based project that uses `spring-boot-starter-web` and `spring-boot-starter-data-jpa`.
|
||||
You can list the capabilities of the service by using the `--list` flag, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring init --list
|
||||
=======================================
|
||||
Capabilities of https://start.spring.io
|
||||
=======================================
|
||||
|
||||
Available dependencies:
|
||||
-----------------------
|
||||
actuator - Actuator: Production ready features to help you monitor and manage your application
|
||||
...
|
||||
web - Web: Support for full-stack web development, including Tomcat and spring-webmvc
|
||||
websocket - Websocket: Support for WebSocket development
|
||||
ws - WS: Support for Spring Web Services
|
||||
|
||||
Available project types:
|
||||
------------------------
|
||||
gradle-build - Gradle Config [format:build, build:gradle]
|
||||
gradle-project - Gradle Project [format:project, build:gradle]
|
||||
maven-build - Maven POM [format:build, build:maven]
|
||||
maven-project - Maven Project [format:project, build:maven] (default)
|
||||
|
||||
...
|
||||
----
|
||||
|
||||
The `init` command supports many options.
|
||||
See the `help` output for more details.
|
||||
For instance, the following command creates a Gradle project that uses Java 8 and `war` packaging:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring init --build=gradle --java-version=1.8 --dependencies=websocket --packaging=war sample-app.zip
|
||||
Using service at https://start.spring.io
|
||||
Content saved to 'sample-app.zip'
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring shell
|
||||
*Spring Boot* (v{spring-boot-version})
|
||||
Hit TAB to complete. Type \'help' and hit RETURN for help, and \'exit' to quit.
|
||||
----
|
||||
|
||||
From inside the embedded shell, you can run other commands directly:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ version
|
||||
Spring CLI v{spring-boot-version}
|
||||
----
|
||||
|
||||
The embedded shell supports ANSI color output as well as `tab` completion.
|
||||
If you need to run a native command, you can use the `!` prefix.
|
||||
To exit the embedded shell, press `ctrl-c`.
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring install com.example:spring-boot-cli-extension:1.0.0.RELEASE
|
||||
----
|
||||
|
||||
In addition to installing the artifacts identified by the coordinates you supply, all of 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 of `group:artifact:version`, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring uninstall com.example:spring-boot-cli-extension:1.0.0.RELEASE
|
||||
----
|
||||
|
||||
It uninstalls the artifacts identified by the coordinates you supply and their dependencies.
|
||||
|
||||
To uninstall all additional dependencies, you can use the `--all` option, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring uninstall --all
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
@Configuration(proxyBeanMethods = false)
|
||||
class Application implements CommandLineRunner {
|
||||
|
||||
@Autowired
|
||||
SharedService service
|
||||
|
||||
@Override
|
||||
void run(String... args) {
|
||||
println service.message
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
import my.company.SharedService
|
||||
|
||||
beans {
|
||||
service(SharedService) {
|
||||
message = "Hello World"
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
You can mix class declarations with `beans{}` in the same file as long as they stay at the top level, or, if you prefer, you can put the beans DSL in a separate file.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
The following configuration settings are honored by the CLI:
|
||||
|
||||
* Offline
|
||||
* Mirrors
|
||||
* Servers
|
||||
* Proxies
|
||||
* Profiles
|
||||
** Activation
|
||||
** Repositories
|
||||
* Active profiles
|
||||
|
||||
See https://maven.apache.org/settings.html[Maven's settings documentation] for further information.
|
||||
|
||||
|
||||
|
||||
[[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].
|
||||
|
||||
If you find that you reach the limit of the CLI tool, you probably want to look at converting your application to a full Gradle or Maven built "`Groovy project`".
|
||||
The next section covers Spring Boot's "<<build-tool-plugins.adoc#build-tool-plugins, Build tool plugins>>", which you can use with Gradle or Maven.
|
||||
include::cli/whats-next.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,30 @@
|
|||
[[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:
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
@Configuration(proxyBeanMethods = false)
|
||||
class Application implements CommandLineRunner {
|
||||
|
||||
@Autowired
|
||||
SharedService service
|
||||
|
||||
@Override
|
||||
void run(String... args) {
|
||||
println service.message
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
import my.company.SharedService
|
||||
|
||||
beans {
|
||||
service(SharedService) {
|
||||
message = "Hello World"
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
You can mix class declarations with `beans{}` in the same file as long as they stay at the top level, or, if you prefer, you can put the beans DSL in a separate file.
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
[[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#getting-started.installing.cli>>_ in the "`Getting started`" section for comprehensive installation instructions.
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
[[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.
|
||||
The following configuration settings are honored by the CLI:
|
||||
|
||||
* Offline
|
||||
* Mirrors
|
||||
* Servers
|
||||
* Proxies
|
||||
* Profiles
|
||||
** Activation
|
||||
** Repositories
|
||||
* Active profiles
|
||||
|
||||
See https://maven.apache.org/settings.html[Maven's settings documentation] for further information.
|
||||
|
|
@ -0,0 +1,356 @@
|
|||
[[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:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring
|
||||
usage: spring [--help] [--version]
|
||||
<command> [<args>]
|
||||
|
||||
Available commands are:
|
||||
|
||||
run [options] <files> [--] [args]
|
||||
Run a spring groovy script
|
||||
|
||||
_... more command help is shown here_
|
||||
----
|
||||
|
||||
You can type `spring help` to get more details about any of the supported commands, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring help run
|
||||
spring run - Run a spring groovy script
|
||||
|
||||
usage: spring run [options] <files> [--] [args]
|
||||
|
||||
Option Description
|
||||
------ -----------
|
||||
--autoconfigure [Boolean] Add autoconfigure compiler
|
||||
transformations (default: true)
|
||||
--classpath, -cp Additional classpath entries
|
||||
--no-guess-dependencies Do not attempt to guess dependencies
|
||||
--no-guess-imports Do not attempt to guess imports
|
||||
-q, --quiet Quiet logging
|
||||
-v, --verbose Verbose logging of dependency
|
||||
resolution
|
||||
--watch Watch the specified file for changes
|
||||
----
|
||||
|
||||
The `version` command provides a quick way to check which version of Spring Boot you are using, as follows:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring version
|
||||
Spring CLI v{spring-boot-version}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
The following example shows a "`hello world`" web application written in Groovy:
|
||||
|
||||
.hello.groovy
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@RestController
|
||||
class WebApplication {
|
||||
|
||||
@RequestMapping("/")
|
||||
String home() {
|
||||
"Hello World!"
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
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 `--` to separate the commands from the "`spring`" command arguments, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring run hello.groovy -- --server.port=9000
|
||||
----
|
||||
|
||||
To set JVM command line arguments, you can use the `JAVA_OPTS` environment variable, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ JAVA_OPTS=-Xmx1024m spring run hello.groovy
|
||||
----
|
||||
|
||||
NOTE: When setting `JAVA_OPTS` on Microsoft Windows, make sure to quote the entire instruction, such as `set "JAVA_OPTS=-Xms256m -Xmx2048m"`.
|
||||
Doing so ensures the values are properly passed to the process.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.deduced-grab-annotations]]
|
||||
==== Deduced "`grab`" Dependencies
|
||||
Standard Groovy includes a `@Grab` annotation, which lets you declare dependencies on third-party libraries.
|
||||
This useful technique lets Groovy download jars in the same way as Maven or Gradle would but without requiring you to use a build tool.
|
||||
|
||||
Spring Boot extends this technique further and tries to deduce which libraries to "`grab`" based on your code.
|
||||
For example, since the `WebApplication` code shown previously uses `@RestController` annotations, Spring Boot grabs "Tomcat" and "Spring MVC".
|
||||
|
||||
The following items are used as "`grab hints`":
|
||||
|
||||
|===
|
||||
| Items | Grabs
|
||||
|
||||
| `JdbcTemplate`, `NamedParameterJdbcTemplate`, `DataSource`
|
||||
| JDBC Application.
|
||||
|
||||
| `@EnableJms`
|
||||
| JMS Application.
|
||||
|
||||
| `@EnableCaching`
|
||||
| Caching abstraction.
|
||||
|
||||
| `@Test`
|
||||
| JUnit.
|
||||
|
||||
| `@EnableRabbit`
|
||||
| RabbitMQ.
|
||||
|
||||
| extends `Specification`
|
||||
| Spock test.
|
||||
|
||||
| `@EnableBatchProcessing`
|
||||
| Spring Batch.
|
||||
|
||||
| `@MessageEndpoint` `@EnableIntegration`
|
||||
| Spring Integration.
|
||||
|
||||
| `@Controller` `@RestController` `@EnableWebMvc`
|
||||
| Spring MVC + Embedded Tomcat.
|
||||
|
||||
| `@EnableWebSecurity`
|
||||
| Spring Security.
|
||||
|
||||
| `@EnableTransactionManagement`
|
||||
| Spring Transaction Management.
|
||||
|===
|
||||
|
||||
TIP: See subclasses of {spring-boot-cli-module-code}/compiler/CompilerAutoConfiguration.java[`CompilerAutoConfiguration`] in the Spring Boot CLI source code to understand exactly how customizations are applied.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.deduced-grab-coordinates]]
|
||||
==== Deduced "`grab`" Coordinates
|
||||
Spring Boot extends Groovy's standard `@Grab` support by letting you specify a dependency without a group or version (for example, `@Grab('freemarker')`).
|
||||
Doing so consults Spring Boot's default dependency metadata to deduce the artifact's group and version.
|
||||
|
||||
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 <<dependency-versions#dependency-versions,appendix>>.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.default-import-statements]]
|
||||
==== Default Import Statements
|
||||
To help reduce the size of your Groovy code, several `import` statements are automatically included.
|
||||
Notice how the preceding example refers to `@Component`, `@RestController`, and `@RequestMapping` without needing to use fully-qualified names or `import` statements.
|
||||
|
||||
TIP: Many Spring annotations work without using `import` statements.
|
||||
Try running your application to see what fails before adding imports.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.automatic-main-method]]
|
||||
==== Automatic Main Method
|
||||
Unlike the equivalent Java application, you do not need to include a `public static void main(String[] args)` method with your `Groovy` scripts.
|
||||
A `SpringApplication` is automatically created, with your compiled code acting as the `source`.
|
||||
|
||||
|
||||
|
||||
[[cli.using-the-cli.run.custom-dependency-management]]
|
||||
==== Custom Dependency Management
|
||||
By default, the CLI uses the dependency management declared in `spring-boot-dependencies` when resolving `@Grab` dependencies.
|
||||
Additional dependency management, which overrides the default dependency management, can be configured by using the `@DependencyManagementBom` annotation.
|
||||
The annotation's value should specify the coordinates (`groupId:artifactId:version`) of one or more Maven BOMs.
|
||||
|
||||
For example, consider the following declaration:
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
@DependencyManagementBom("com.example.custom-bom:1.0.0")
|
||||
----
|
||||
|
||||
The preceding declaration picks up `custom-bom-1.0.0.pom` in a Maven repository under `com/example/custom-versions/1.0.0/`.
|
||||
|
||||
When you specify multiple BOMs, they are applied in the order in which you declare them, as shown in the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
@DependencyManagementBom(["com.example.custom-bom:1.0.0",
|
||||
"com.example.another-bom:1.0.0"])
|
||||
----
|
||||
|
||||
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 `@DependencyManagementBom` at most once in your application.
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring run *.groovy
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring jar my-app.jar *.groovy
|
||||
----
|
||||
|
||||
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 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]
|
||||
----
|
||||
public/**, resources/**, static/**, templates/**, META-INF/**, *
|
||||
----
|
||||
|
||||
The default excludes are as follows:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
.*, repository/**, build/**, target/**, **/*.jar, **/*.groovy
|
||||
----
|
||||
|
||||
Type `spring help jar` on the command line for more information.
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring init --dependencies=web,data-jpa my-project
|
||||
Using service at https://start.spring.io
|
||||
Project extracted to '/Users/developer/example/my-project'
|
||||
----
|
||||
|
||||
The preceding example creates a `my-project` directory with a Maven-based project that uses `spring-boot-starter-web` and `spring-boot-starter-data-jpa`.
|
||||
You can list the capabilities of the service by using the `--list` flag, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring init --list
|
||||
=======================================
|
||||
Capabilities of https://start.spring.io
|
||||
=======================================
|
||||
|
||||
Available dependencies:
|
||||
-----------------------
|
||||
actuator - Actuator: Production ready features to help you monitor and manage your application
|
||||
...
|
||||
web - Web: Support for full-stack web development, including Tomcat and spring-webmvc
|
||||
websocket - Websocket: Support for WebSocket development
|
||||
ws - WS: Support for Spring Web Services
|
||||
|
||||
Available project types:
|
||||
------------------------
|
||||
gradle-build - Gradle Config [format:build, build:gradle]
|
||||
gradle-project - Gradle Project [format:project, build:gradle]
|
||||
maven-build - Maven POM [format:build, build:maven]
|
||||
maven-project - Maven Project [format:project, build:maven] (default)
|
||||
|
||||
...
|
||||
----
|
||||
|
||||
The `init` command supports many options.
|
||||
See the `help` output for more details.
|
||||
For instance, the following command creates a Gradle project that uses Java 8 and `war` packaging:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ spring init --build=gradle --java-version=1.8 --dependencies=websocket --packaging=war sample-app.zip
|
||||
Using service at https://start.spring.io
|
||||
Content saved to 'sample-app.zip'
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring shell
|
||||
*Spring Boot* (v{spring-boot-version})
|
||||
Hit TAB to complete. Type \'help' and hit RETURN for help, and \'exit' to quit.
|
||||
----
|
||||
|
||||
From inside the embedded shell, you can run other commands directly:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ version
|
||||
Spring CLI v{spring-boot-version}
|
||||
----
|
||||
|
||||
The embedded shell supports ANSI color output as well as `tab` completion.
|
||||
If you need to run a native command, you can use the `!` prefix.
|
||||
To exit the embedded shell, press `ctrl-c`.
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring install com.example:spring-boot-cli-extension:1.0.0.RELEASE
|
||||
----
|
||||
|
||||
In addition to installing the artifacts identified by the coordinates you supply, all of 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 of `group:artifact:version`, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring uninstall com.example:spring-boot-cli-extension:1.0.0.RELEASE
|
||||
----
|
||||
|
||||
It uninstalls the artifacts identified by the coordinates you supply and their dependencies.
|
||||
|
||||
To uninstall all additional dependencies, you can use the `--all` option, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring uninstall --all
|
||||
----
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
[[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].
|
||||
|
||||
If you find that you reach the limit of the CLI tool, you probably want to look at converting your application to a full Gradle or Maven built "`Groovy project`".
|
||||
The next section covers Spring Boot's "<<build-tool-plugins#build-tool-plugins, Build tool plugins>>", which you can use with Gradle or Maven.
|
||||
|
|
@ -1,109 +0,0 @@
|
|||
:numbered!:
|
||||
[appendix]
|
||||
[[appendix.common-application-properties]]
|
||||
= Common Application properties
|
||||
include::attributes.adoc[]
|
||||
|
||||
Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
|
||||
This appendix provides a list of common 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 <<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.
|
||||
Also, you can define your own properties.
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.core]]
|
||||
== Core Properties [[core-properties]]
|
||||
include::config-docs/core.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.cache]]
|
||||
== Cache Properties [[cache-properties]]
|
||||
include::config-docs/cache.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.mail]]
|
||||
== Mail Properties [[mail-properties]]
|
||||
include::config-docs/mail.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.json]]
|
||||
== JSON Properties [[json-properties]]
|
||||
include::config-docs/json.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.data]]
|
||||
== Data Properties [[data-properties]]
|
||||
include::config-docs/data.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.transaction]]
|
||||
== Transaction Properties [[transaction-properties]]
|
||||
include::config-docs/transaction.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.data-migration]]
|
||||
== Data Migration Properties [[data-migration-properties]]
|
||||
include::config-docs/data-migration.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.integration]]
|
||||
== Integration Properties [[integration-properties]]
|
||||
include::config-docs/integration.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.web]]
|
||||
== Web Properties [[web-properties]]
|
||||
include::config-docs/web.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.templating]]
|
||||
== Templating Properties [[templating-properties]]
|
||||
include::config-docs/templating.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.server]]
|
||||
== Server Properties [[server-properties]]
|
||||
include::config-docs/server.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.security]]
|
||||
== Security Properties [[security-properties]]
|
||||
include::config-docs/security.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.rsocket]]
|
||||
== RSocket Properties [[rsocket-properties]]
|
||||
include::config-docs/rsocket.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.actuator]]
|
||||
== Actuator Properties [[actuator-properties]]
|
||||
include::config-docs/actuator.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.devtools]]
|
||||
== Devtools Properties [[devtools-properties]]
|
||||
include::config-docs/devtools.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.common-application-properties.testing]]
|
||||
== Testing Properties [[testing-properties]]
|
||||
include::config-docs/testing.adoc[]
|
||||
|
|
@ -1,902 +1,20 @@
|
|||
[appendix]
|
||||
[[appendix.configuration-metadata]]
|
||||
[[configuration-metadata]]
|
||||
= Configuration Metadata
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
Spring Boot jars include metadata files that provide details of all supported configuration properties.
|
||||
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 <<appendix.configuration-metadata.annotation-processor.adding-additional-metadata,write part of the metadata manually>> for corner cases or more advanced use cases.
|
||||
However, it is possible to <<configuration-metadata#configuration-metadata.annotation-processor.adding-additional-metadata,write part of the metadata manually>> for corner cases or more advanced use cases.
|
||||
|
||||
|
||||
|
||||
[[appendix.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:
|
||||
include::configuration-metadata/format.adoc[]
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"groups": [
|
||||
{
|
||||
"name": "server",
|
||||
"type": "org.springframework.boot.autoconfigure.web.ServerProperties",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
|
||||
},
|
||||
{
|
||||
"name": "spring.jpa.hibernate",
|
||||
"type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties",
|
||||
"sourceMethod": "getHibernate()"
|
||||
}
|
||||
...
|
||||
],"properties": [
|
||||
{
|
||||
"name": "server.port",
|
||||
"type": "java.lang.Integer",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
|
||||
},
|
||||
{
|
||||
"name": "server.address",
|
||||
"type": "java.net.InetAddress",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
|
||||
},
|
||||
{
|
||||
"name": "spring.jpa.hibernate.ddl-auto",
|
||||
"type": "java.lang.String",
|
||||
"description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"
|
||||
}
|
||||
...
|
||||
],"hints": [
|
||||
{
|
||||
"name": "spring.jpa.hibernate.ddl-auto",
|
||||
"values": [
|
||||
{
|
||||
"value": "none",
|
||||
"description": "Disable DDL handling."
|
||||
},
|
||||
{
|
||||
"value": "validate",
|
||||
"description": "Validate the schema, make no changes to the database."
|
||||
},
|
||||
{
|
||||
"value": "update",
|
||||
"description": "Update the schema if necessary."
|
||||
},
|
||||
{
|
||||
"value": "create",
|
||||
"description": "Create the schema and destroy previous data."
|
||||
},
|
||||
{
|
||||
"value": "create-drop",
|
||||
"description": "Create and then destroy the schema at the end of the session."
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
include::configuration-metadata/manual-hints.adoc[]
|
||||
|
||||
Each "`property`" is a configuration item that the user specifies with a given value.
|
||||
For example, `server.port` and `server.address` might be specified in `application.properties`, as follows:
|
||||
|
||||
[source,properties,indent=0,configprops]
|
||||
----
|
||||
server.port=9090
|
||||
server.address=127.0.0.1
|
||||
----
|
||||
|
||||
The "`groups`" are higher level items that do not themselves specify a value but instead provide a contextual grouping for properties.
|
||||
For example, the `server.port` and `server.address` properties are part of the `server` group.
|
||||
|
||||
NOTE: It is not required that every "`property`" has a "`group`".
|
||||
Some properties might exist in their own right.
|
||||
|
||||
Finally, "`hints`" are additional information used to assist the user in configuring a given property.
|
||||
For example, when a developer is configuring the configprop:spring.jpa.hibernate.ddl-auto[] property, a tool can use the hints to offer some auto-completion help for the `none`, `validate`, `update`, `create`, and `create-drop` values.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.format.group]]
|
||||
=== Group Attributes
|
||||
The JSON object contained in the `groups` array can contain the attributes shown in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `name`
|
||||
| String
|
||||
| The full name of the group.
|
||||
This attribute is mandatory.
|
||||
|
||||
| `type`
|
||||
| String
|
||||
| The class name of the data type of the group.
|
||||
For example, if the group were based on a class annotated with `@ConfigurationProperties`, the attribute would contain the fully qualified name of that class.
|
||||
If it were based on a `@Bean` method, it would be the return type of that method.
|
||||
If the type is not known, the attribute may be omitted.
|
||||
|
||||
| `description`
|
||||
| String
|
||||
| A short description of the group that can be displayed to users.
|
||||
If no description is available, it may be omitted.
|
||||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||||
The last line in the description should end with a period (`.`).
|
||||
|
||||
| `sourceType`
|
||||
| String
|
||||
| The class name of the source that contributed this group.
|
||||
For example, if the group were based on a `@Bean` method annotated with `@ConfigurationProperties`, this attribute would contain the fully qualified name of the `@Configuration` class that contains the method.
|
||||
If the source type is not known, the attribute may be omitted.
|
||||
|
||||
| `sourceMethod`
|
||||
| String
|
||||
| The full name of the method (include parenthesis and argument types) that contributed this group (for example, the name of a `@ConfigurationProperties` annotated `@Bean` method).
|
||||
If the source method is not known, it may be omitted.
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.format.property]]
|
||||
=== Property Attributes
|
||||
The JSON object contained in the `properties` array can contain the attributes described in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `name`
|
||||
| String
|
||||
| The full name of the property.
|
||||
Names are in lower-case period-separated form (for example, `server.address`).
|
||||
This attribute is mandatory.
|
||||
|
||||
| `type`
|
||||
| String
|
||||
| The full signature of the data type of the property (for example, `java.lang.String`) but also a full generic type (such as `java.util.Map<java.lang.String,acme.MyEnum>`).
|
||||
You can use this attribute to guide the user as to the types of values that they can enter.
|
||||
For consistency, the type of a primitive is specified by using its wrapper counterpart (for example, `boolean` becomes `java.lang.Boolean`).
|
||||
Note that this class may be a complex type that gets converted from a `String` as values are bound.
|
||||
If the type is not known, it may be omitted.
|
||||
|
||||
| `description`
|
||||
| String
|
||||
| A short description of the property that can be displayed to users.
|
||||
If no description is available, it may be omitted.
|
||||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||||
The last line in the description should end with a period (`.`).
|
||||
|
||||
| `sourceType`
|
||||
| String
|
||||
| The class name of the source that contributed this property.
|
||||
For example, if the property were from a class annotated with `@ConfigurationProperties`, this attribute would contain the fully qualified name of that class.
|
||||
If the source type is unknown, it may be omitted.
|
||||
|
||||
| `defaultValue`
|
||||
| Object
|
||||
| The default value, which is used if the property is not specified.
|
||||
If the type of the property is an array, it can be an array of value(s).
|
||||
If the default value is unknown, it may be omitted.
|
||||
|
||||
| `deprecation`
|
||||
| Deprecation
|
||||
| Specify whether the property is deprecated.
|
||||
If the field is not deprecated or if that information is not known, it may be omitted.
|
||||
The next table offers more detail about the `deprecation` attribute.
|
||||
|===
|
||||
|
||||
The JSON object contained in the `deprecation` attribute of each `properties` element can contain the following attributes:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `level`
|
||||
| String
|
||||
| The level of deprecation, which can be either `warning` (the default) or `error`.
|
||||
When a property has a `warning` deprecation level, it should still be bound in the environment.
|
||||
However, when it has an `error` deprecation level, the property is no longer managed and is not bound.
|
||||
|
||||
| `reason`
|
||||
| String
|
||||
| A short description of the reason why the property was deprecated.
|
||||
If no reason is available, it may be omitted.
|
||||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||||
The last line in the description should end with a period (`.`).
|
||||
|
||||
| `replacement`
|
||||
| String
|
||||
| The full name of the property that _replaces_ this deprecated property.
|
||||
If there is no replacement for this property, it may be omitted.
|
||||
|===
|
||||
|
||||
NOTE: Prior to Spring Boot 1.3, a single `deprecated` boolean attribute can be used instead of the `deprecation` element.
|
||||
This is still supported in a deprecated fashion and should no longer be used.
|
||||
If no reason and replacement are available, an empty `deprecation` object should be set.
|
||||
|
||||
Deprecation can also be specified declaratively in code by adding the `@DeprecatedConfigurationProperty` annotation to the getter exposing the deprecated property.
|
||||
For instance, assume that the `app.acme.target` property was confusing and was renamed to `app.acme.name`.
|
||||
The following example shows how to handle that situation:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
@ConfigurationProperties("app.acme")
|
||||
public class AcmeProperties {
|
||||
|
||||
private String name;
|
||||
|
||||
public String getName() { ... }
|
||||
|
||||
public void setName(String name) { ... }
|
||||
|
||||
@DeprecatedConfigurationProperty(replacement = "app.acme.name")
|
||||
@Deprecated
|
||||
public String getTarget() {
|
||||
return getName();
|
||||
}
|
||||
|
||||
@Deprecated
|
||||
public void setTarget(String target) {
|
||||
setName(target);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
NOTE: There is no way to set a `level`.
|
||||
`warning` is always assumed, since code is still handling the property.
|
||||
|
||||
The preceding code makes sure that the deprecated property still works (delegating to the `name` property behind the scenes).
|
||||
Once the `getTarget` and `setTarget` methods can be removed from your public API, the automatic deprecation hint in the metadata goes away as well.
|
||||
If you want to keep a hint, adding manual metadata with an `error` deprecation level ensures that users are still informed about that property.
|
||||
Doing so is particularly useful when a `replacement` is provided.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.format.hints]]
|
||||
=== Hint Attributes
|
||||
The JSON object contained in the `hints` array can contain the attributes shown in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `name`
|
||||
| String
|
||||
| The full name of the property to which this hint refers.
|
||||
Names are in lower-case period-separated form (such as `spring.mvc.servlet.path`).
|
||||
If the property refers to a map (such as `system.contexts`), the hint either applies to the _keys_ of the map (`system.contexts.keys`) or the _values_ (`system.contexts.values`) of the map.
|
||||
This attribute is mandatory.
|
||||
|
||||
| `values`
|
||||
| ValueHint[]
|
||||
| A list of valid values as defined by the `ValueHint` object (described in the next table).
|
||||
Each entry defines the value and may have a description.
|
||||
|
||||
| `providers`
|
||||
| ValueProvider[]
|
||||
| A list of providers as defined by the `ValueProvider` object (described later in this document).
|
||||
Each entry defines the name of the provider and its parameters, if any.
|
||||
|===
|
||||
|
||||
The JSON object contained in the `values` attribute of each `hint` element can contain the attributes described in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `value`
|
||||
| Object
|
||||
| A valid value for the element to which the hint refers.
|
||||
If the type of the property is an array, it can also be an array of value(s).
|
||||
This attribute is mandatory.
|
||||
|
||||
| `description`
|
||||
| String
|
||||
| A short description of the value that can be displayed to users.
|
||||
If no description is available, it may be omitted.
|
||||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||||
The last line in the description should end with a period (`.`).
|
||||
|===
|
||||
|
||||
The JSON object contained in the `providers` attribute of each `hint` element can contain the attributes described in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
|Name | Type |Purpose
|
||||
|
||||
| `name`
|
||||
| String
|
||||
| The name of the provider to use to offer additional content assistance for the element to which the hint refers.
|
||||
|
||||
| `parameters`
|
||||
| JSON object
|
||||
| Any additional parameter that the provider supports (check the documentation of the provider for more details).
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
While the same names appearing in the metadata multiple times should not be common, consumers of metadata should take care to ensure that they support it.
|
||||
|
||||
|
||||
|
||||
[[appendix.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:
|
||||
|
||||
* Describes the list of potential values for a property.
|
||||
* Associates a provider, to attach a well defined semantic to a property, so that a tool can discover the list of potential values based on the project's context.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.manual-hints.value-hint]]
|
||||
=== Value Hint
|
||||
The `name` attribute of each hint refers to the `name` of a property.
|
||||
In the <<appendix.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).
|
||||
The special `.keys` and `.values` suffixes must refer to the keys and the values, respectively.
|
||||
|
||||
Assume a `sample.contexts` maps magic `String` values to an integer, as shown in the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
@ConfigurationProperties("sample")
|
||||
public class SampleProperties {
|
||||
|
||||
private Map<String,Integer> contexts;
|
||||
// getters and setters
|
||||
}
|
||||
----
|
||||
|
||||
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 <<appendix.configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "sample.contexts.keys",
|
||||
"values": [
|
||||
{
|
||||
"value": "sample1"
|
||||
},
|
||||
{
|
||||
"value": "sample2"
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
TIP: We recommend that you use an `Enum` for those two values instead.
|
||||
If your IDE supports it, this is by far the most effective approach to auto-completion.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.manual-hints.value-providers]]
|
||||
=== Value Providers
|
||||
Providers are a powerful way to attach semantics to a property.
|
||||
In this section, we define the official providers that you can use for your own hints.
|
||||
However, your favorite IDE may implement some of these or none of them.
|
||||
Also, it could eventually provide its own.
|
||||
|
||||
NOTE: As this is a new feature, IDE vendors must catch up with how it works.
|
||||
Adoption times naturally vary.
|
||||
|
||||
The following table summarizes the list of supported providers:
|
||||
|
||||
[cols="2,4"]
|
||||
|===
|
||||
| Name | Description
|
||||
|
||||
| `any`
|
||||
| Permits any additional value to be provided.
|
||||
|
||||
| `class-reference`
|
||||
| Auto-completes the classes available in the project.
|
||||
Usually constrained by a base class that is specified by the `target` parameter.
|
||||
|
||||
| `handle-as`
|
||||
| Handles the property as if it were defined by the type defined by the mandatory `target` parameter.
|
||||
|
||||
| `logger-name`
|
||||
| Auto-completes valid logger names and <<features.adoc#features.logging.log-groups,logger groups>>.
|
||||
Typically, package and class names available in the current project can be auto-completed as well as defined groups.
|
||||
|
||||
| `spring-bean-reference`
|
||||
| Auto-completes the available bean names in the current project.
|
||||
Usually constrained by a base class that is specified by the `target` parameter.
|
||||
|
||||
| `spring-profile-name`
|
||||
| Auto-completes the available Spring profile names in the project.
|
||||
|===
|
||||
|
||||
TIP: Only one provider can be active for a given property, but you can specify several providers if they can all manage the property _in some way_.
|
||||
Make sure to place the most powerful provider first, as the IDE must use the first one in the JSON section that it can handle.
|
||||
If no provider for a given property is supported, no special content assistance is provided, either.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.manual-hints.value-providers.any]]
|
||||
==== Any
|
||||
The special **any** provider value permits any additional values to be provided.
|
||||
Regular value validation based on the property type should be applied if this is supported.
|
||||
|
||||
This provider is typically used if you have a list of values and any extra values should still be considered as valid.
|
||||
|
||||
The following example offers `on` and `off` as auto-completion values for `system.state`:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "system.state",
|
||||
"values": [
|
||||
{
|
||||
"value": "on"
|
||||
},
|
||||
{
|
||||
"value": "off"
|
||||
}
|
||||
],
|
||||
"providers": [
|
||||
{
|
||||
"name": "any"
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
Note that, in the preceding example, any other value is also allowed.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.manual-hints.value-providers.class-reference]]
|
||||
==== Class Reference
|
||||
The **class-reference** provider auto-completes classes available in the project.
|
||||
This provider supports the following parameters:
|
||||
|
||||
[cols="1,1,2,4"]
|
||||
|===
|
||||
| Parameter | Type | Default value | Description
|
||||
|
||||
| `target`
|
||||
| `String` (`Class`)
|
||||
| _none_
|
||||
| The fully qualified name of the class that should be assignable to the chosen value.
|
||||
Typically used to filter out-non candidate classes.
|
||||
Note that this information can be provided by the type itself by exposing a class with the appropriate upper bound.
|
||||
|
||||
| `concrete`
|
||||
| `boolean`
|
||||
| true
|
||||
| Specify whether only concrete classes are to be considered as valid candidates.
|
||||
|===
|
||||
|
||||
|
||||
The following metadata snippet corresponds to the standard `server.servlet.jsp.class-name` property that defines the `JspServlet` class name to use:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "server.servlet.jsp.class-name",
|
||||
"providers": [
|
||||
{
|
||||
"name": "class-reference",
|
||||
"parameters": {
|
||||
"target": "javax.servlet.http.HttpServlet"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.manual-hints.value-providers.handle-as]]
|
||||
==== Handle As
|
||||
The **handle-as** provider lets you substitute the type of the property to a more high-level type.
|
||||
This typically happens when the property has a `java.lang.String` type, because you do not want your configuration classes to rely on classes that may not be on the classpath.
|
||||
This provider supports the following parameters:
|
||||
|
||||
[cols="1,1,2,4"]
|
||||
|===
|
||||
| Parameter | Type | Default value | Description
|
||||
|
||||
| **`target`**
|
||||
| `String` (`Class`)
|
||||
| _none_
|
||||
| The fully qualified name of the type to consider for the property.
|
||||
This parameter is mandatory.
|
||||
|===
|
||||
|
||||
The following types can be used:
|
||||
|
||||
* Any `java.lang.Enum`: Lists the possible values for the property.
|
||||
(We recommend defining the property with the `Enum` type, as no further hint should be required for the IDE to auto-complete the values)
|
||||
* `java.nio.charset.Charset`: Supports auto-completion of charset/encoding values (such as `UTF-8`)
|
||||
* `java.util.Locale`: auto-completion of locales (such as `en_US`)
|
||||
* `org.springframework.util.MimeType`: Supports auto-completion of content type values (such as `text/plain`)
|
||||
* `org.springframework.core.io.Resource`: Supports auto-completion of Spring’s Resource abstraction to refer to a file on the filesystem or on the classpath (such as `classpath:/sample.properties`)
|
||||
|
||||
TIP: If multiple values can be provided, use a `Collection` or _Array_ type to teach the IDE about it.
|
||||
|
||||
The following metadata snippet corresponds to the standard `spring.liquibase.change-log` property that defines the path to the changelog to use.
|
||||
It is actually used internally as a `org.springframework.core.io.Resource` but cannot be exposed as such, because we need to keep the original String value to pass it to the Liquibase API.
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "spring.liquibase.change-log",
|
||||
"providers": [
|
||||
{
|
||||
"name": "handle-as",
|
||||
"parameters": {
|
||||
"target": "org.springframework.core.io.Resource"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.manual-hints.value-providers.logger-name]]
|
||||
==== Logger Name
|
||||
The **logger-name** provider auto-completes valid logger names and <<features.adoc#features.logging.log-groups,logger groups>>.
|
||||
Typically, package and class names available in the current project can be auto-completed.
|
||||
If groups are enabled (default) and if a custom logger group is identified in the configuration, auto-completion for it should be provided.
|
||||
Specific frameworks may have extra magic logger names that can be supported as well.
|
||||
|
||||
This provider supports the following parameters:
|
||||
|
||||
[cols="1,1,2,4"]
|
||||
|===
|
||||
| Parameter | Type | Default value | Description
|
||||
|
||||
| `group`
|
||||
| `boolean`
|
||||
| `true`
|
||||
| Specify whether known groups should be considered.
|
||||
|===
|
||||
|
||||
Since a logger name can be any arbitrary name, this provider should allow any value but could highlight valid package and class names that are not available in the project's classpath.
|
||||
|
||||
The following metadata snippet corresponds to the standard `logging.level` property.
|
||||
Keys are _logger names_, and values correspond to the standard log levels or any custom level.
|
||||
As Spring Boot defines a few logger groups out-of-the-box, dedicated value hints have been added for those.
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "logging.level.keys",
|
||||
"values": [
|
||||
{
|
||||
"value": "root",
|
||||
"description": "Root logger used to assign the default logging level."
|
||||
},
|
||||
{
|
||||
"value": "sql",
|
||||
"description": "SQL logging group including Hibernate SQL logger."
|
||||
},
|
||||
{
|
||||
"value": "web",
|
||||
"description": "Web logging group including codecs."
|
||||
}
|
||||
],
|
||||
"providers": [
|
||||
{
|
||||
"name": "logger-name"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "logging.level.values",
|
||||
"values": [
|
||||
{
|
||||
"value": "trace"
|
||||
},
|
||||
{
|
||||
"value": "debug"
|
||||
},
|
||||
{
|
||||
"value": "info"
|
||||
},
|
||||
{
|
||||
"value": "warn"
|
||||
},
|
||||
{
|
||||
"value": "error"
|
||||
},
|
||||
{
|
||||
"value": "fatal"
|
||||
},
|
||||
{
|
||||
"value": "off"
|
||||
}
|
||||
|
||||
],
|
||||
"providers": [
|
||||
{
|
||||
"name": "any"
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.manual-hints.value-providers.spring-bean-reference]]
|
||||
==== Spring Bean Reference
|
||||
The **spring-bean-reference** provider auto-completes the beans that are defined in the configuration of the current project.
|
||||
This provider supports the following parameters:
|
||||
|
||||
[cols="1,1,2,4"]
|
||||
|===
|
||||
| Parameter | Type | Default value | Description
|
||||
|
||||
| `target`
|
||||
| `String` (`Class`)
|
||||
| _none_
|
||||
| The fully qualified name of the bean class that should be assignable to the candidate.
|
||||
Typically used to filter out non-candidate beans.
|
||||
|===
|
||||
|
||||
The following metadata snippet corresponds to the standard `spring.jmx.server` property that defines the name of the `MBeanServer` bean to use:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "spring.jmx.server",
|
||||
"providers": [
|
||||
{
|
||||
"name": "spring-bean-reference",
|
||||
"parameters": {
|
||||
"target": "javax.management.MBeanServer"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
NOTE: The binder is not aware of the metadata.
|
||||
If you provide that hint, you still need to transform the bean name into an actual Bean reference using by the `ApplicationContext`.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.manual-hints.value-providers.spring-profile-name]]
|
||||
==== Spring Profile Name
|
||||
The **spring-profile-name** provider auto-completes the Spring profiles that are defined in the configuration of the current project.
|
||||
|
||||
The following metadata snippet corresponds to the standard `spring.profiles.active` property that defines the name of the Spring profile(s) to enable:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "spring.profiles.active",
|
||||
"providers": [
|
||||
{
|
||||
"name": "spring-profile-name"
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.annotation-processor.configuring]]
|
||||
=== Configuring the Annotation Processor
|
||||
To use the processor, include a dependency on `spring-boot-configuration-processor`.
|
||||
|
||||
With Maven the dependency should be declared as optional, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-configuration-processor</artifactId>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
With Gradle, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
|
||||
}
|
||||
----
|
||||
|
||||
If you are using an `additional-spring-configuration-metadata.json` file, the `compileJava` task should be configured to depend on the `processResources` task, as shown in the following example:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
compileJava.inputs.files(processResources)
|
||||
----
|
||||
|
||||
This dependency ensures that the additional metadata is available when the annotation processor runs during compilation.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
If you are using AspectJ in your project, you need to make sure that the annotation processor runs only once.
|
||||
There are several ways to do this.
|
||||
With Maven, you can configure the `maven-apt-plugin` explicitly and add the dependency to the annotation processor only there.
|
||||
You could also let the AspectJ plugin run all the processing and disable annotation processing in the `maven-compiler-plugin` configuration, as follows:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<configuration>
|
||||
<proc>none</proc>
|
||||
</configuration>
|
||||
</plugin>
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.annotation-processor.automatic-metadata-generation]]
|
||||
=== Automatic Metadata Generation
|
||||
The processor picks up both classes and methods that are annotated with `@ConfigurationProperties`.
|
||||
|
||||
If the class is also annotated with `@ConstructorBinding`, a single constructor is expected and one property is created per constructor parameter.
|
||||
Otherwise, properties are discovered through the presence of standard getters and setters with special handling for collection and map types (that is detected even if only a getter is present).
|
||||
The annotation processor also supports the use of the `@Data`, `@Getter`, and `@Setter` lombok annotations.
|
||||
|
||||
Consider the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
@ConfigurationProperties(prefix="server")
|
||||
public class ServerProperties {
|
||||
|
||||
/**
|
||||
* Name of the server.
|
||||
*/
|
||||
private String name;
|
||||
|
||||
/**
|
||||
* IP address to listen to.
|
||||
*/
|
||||
private String ip = "127.0.0.1";
|
||||
|
||||
/**
|
||||
* Port to listener to.
|
||||
*/
|
||||
private int port = 9797;
|
||||
|
||||
// ... getter and setters
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
This exposes three properties where `server.name` has no default and `server.ip` and `server.port` defaults to `"127.0.0.1"` and `9797` respectively.
|
||||
The Javadoc on fields is used to populate the `description` attribute. For instance, the description of `server.ip` is "IP address to listen to.".
|
||||
|
||||
NOTE: You should only use plain text with `@ConfigurationProperties` field Javadoc, since they are not processed before being added to the JSON.
|
||||
|
||||
The annotation processor applies a number of heuristics to extract the default value from the source model.
|
||||
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, <<appendix.configuration-metadata.annotation-processor.adding-additional-metadata,manual metadata>> should be provided.
|
||||
Consider the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@ConfigurationProperties(prefix = "acme.messaging")
|
||||
public class MessagingProperties {
|
||||
|
||||
private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b"));
|
||||
|
||||
private ContainerType containerType = ContainerType.SIMPLE;
|
||||
|
||||
// ... getter and setters
|
||||
|
||||
public enum ContainerType {
|
||||
|
||||
SIMPLE,
|
||||
DIRECT
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
In order to document default values for properties in the class above, you could add the following content to <<appendix.configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"properties": [
|
||||
{
|
||||
"name": "acme.messaging.addresses",
|
||||
"defaultValue": ["a", "b"]
|
||||
},
|
||||
{
|
||||
"name": "acme.messaging.container-type",
|
||||
"defaultValue": "simple"
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
NOTE: Only the `name` of the property is required to document additional metadata for existing properties.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.annotation-processor.automatic-metadata-generation.nested-properties]]
|
||||
==== Nested Properties
|
||||
The annotation processor automatically considers inner classes as nested properties.
|
||||
Rather than documenting the `ip` and `port` at the root of the namespace, we could create a sub-namespace for it.
|
||||
Consider the updated example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@ConfigurationProperties(prefix="server")
|
||||
public class ServerProperties {
|
||||
|
||||
private String name;
|
||||
|
||||
private Host host;
|
||||
|
||||
// ... getter and setters
|
||||
|
||||
public static class Host {
|
||||
|
||||
private String ip;
|
||||
|
||||
private int port;
|
||||
|
||||
// ... getter and setters
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
The preceding example produces metadata information for `server.name`, `server.host.ip`, and `server.host.port` properties.
|
||||
You can use the `@NestedConfigurationProperty` annotation on a field to indicate that a regular (non-inner) class should be treated as if it were nested.
|
||||
|
||||
TIP: This has no effect on collections and maps, as those types are automatically identified, and a single metadata property is generated for each of them.
|
||||
|
||||
|
||||
|
||||
[[appendix.configuration-metadata.annotation-processor.adding-additional-metadata]]
|
||||
=== Adding Additional Metadata
|
||||
Spring Boot's configuration file handling is quite flexible, and it is often the case that properties may exist that are not bound to a `@ConfigurationProperties` bean.
|
||||
You may also need to tune some attributes of an existing key.
|
||||
To support such cases and let you provide custom "hints", the annotation processor automatically merges items from `META-INF/additional-spring-configuration-metadata.json` into the main metadata file.
|
||||
|
||||
If you refer to a property that has been detected automatically, the description, default value, and deprecation information are overridden, if specified.
|
||||
If the manual property declaration is not identified in the current module, it is added as a new property.
|
||||
|
||||
The format of the `additional-spring-configuration-metadata.json` file is exactly the same as the regular `spring-configuration-metadata.json`.
|
||||
The additional properties file is optional.
|
||||
If you do not have any additional properties, do not add the file.
|
||||
include::configuration-metadata/annotation-processor.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,198 @@
|
|||
[[configuration-metadata.annotation-processor]]
|
||||
== Generating Your Own Metadata by Using the Annotation Processor
|
||||
You can easily generate your own configuration metadata file from items annotated with `@ConfigurationProperties` by using the `spring-boot-configuration-processor` jar.
|
||||
The jar includes a Java annotation processor which is invoked as your project is compiled.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.annotation-processor.configuring]]
|
||||
=== Configuring the Annotation Processor
|
||||
To use the processor, include a dependency on `spring-boot-configuration-processor`.
|
||||
|
||||
With Maven the dependency should be declared as optional, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-configuration-processor</artifactId>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
With Gradle, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
|
||||
}
|
||||
----
|
||||
|
||||
If you are using an `additional-spring-configuration-metadata.json` file, the `compileJava` task should be configured to depend on the `processResources` task, as shown in the following example:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
compileJava.inputs.files(processResources)
|
||||
----
|
||||
|
||||
This dependency ensures that the additional metadata is available when the annotation processor runs during compilation.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
If you are using AspectJ in your project, you need to make sure that the annotation processor runs only once.
|
||||
There are several ways to do this.
|
||||
With Maven, you can configure the `maven-apt-plugin` explicitly and add the dependency to the annotation processor only there.
|
||||
You could also let the AspectJ plugin run all the processing and disable annotation processing in the `maven-compiler-plugin` configuration, as follows:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<configuration>
|
||||
<proc>none</proc>
|
||||
</configuration>
|
||||
</plugin>
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.annotation-processor.automatic-metadata-generation]]
|
||||
=== Automatic Metadata Generation
|
||||
The processor picks up both classes and methods that are annotated with `@ConfigurationProperties`.
|
||||
|
||||
If the class is also annotated with `@ConstructorBinding`, a single constructor is expected and one property is created per constructor parameter.
|
||||
Otherwise, properties are discovered through the presence of standard getters and setters with special handling for collection and map types (that is detected even if only a getter is present).
|
||||
The annotation processor also supports the use of the `@Data`, `@Getter`, and `@Setter` lombok annotations.
|
||||
|
||||
Consider the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
@ConfigurationProperties(prefix="server")
|
||||
public class ServerProperties {
|
||||
|
||||
/**
|
||||
* Name of the server.
|
||||
*/
|
||||
private String name;
|
||||
|
||||
/**
|
||||
* IP address to listen to.
|
||||
*/
|
||||
private String ip = "127.0.0.1";
|
||||
|
||||
/**
|
||||
* Port to listener to.
|
||||
*/
|
||||
private int port = 9797;
|
||||
|
||||
// ... getter and setters
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
This exposes three properties where `server.name` has no default and `server.ip` and `server.port` defaults to `"127.0.0.1"` and `9797` respectively.
|
||||
The Javadoc on fields is used to populate the `description` attribute. For instance, the description of `server.ip` is "IP address to listen to.".
|
||||
|
||||
NOTE: You should only use plain text with `@ConfigurationProperties` field Javadoc, since they are not processed before being added to the JSON.
|
||||
|
||||
The annotation processor applies a number of heuristics to extract the default value from the source model.
|
||||
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#configuration-metadata.annotation-processor.adding-additional-metadata,manual metadata>> should be provided.
|
||||
Consider the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@ConfigurationProperties(prefix = "acme.messaging")
|
||||
public class MessagingProperties {
|
||||
|
||||
private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b"));
|
||||
|
||||
private ContainerType containerType = ContainerType.SIMPLE;
|
||||
|
||||
// ... getter and setters
|
||||
|
||||
public enum ContainerType {
|
||||
|
||||
SIMPLE,
|
||||
DIRECT
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
In order to document default values for properties in the class above, you could add the following content to <<configuration-metadata#configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"properties": [
|
||||
{
|
||||
"name": "acme.messaging.addresses",
|
||||
"defaultValue": ["a", "b"]
|
||||
},
|
||||
{
|
||||
"name": "acme.messaging.container-type",
|
||||
"defaultValue": "simple"
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
NOTE: Only the `name` of the property is required to document additional metadata for existing properties.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.annotation-processor.automatic-metadata-generation.nested-properties]]
|
||||
==== Nested Properties
|
||||
The annotation processor automatically considers inner classes as nested properties.
|
||||
Rather than documenting the `ip` and `port` at the root of the namespace, we could create a sub-namespace for it.
|
||||
Consider the updated example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@ConfigurationProperties(prefix="server")
|
||||
public class ServerProperties {
|
||||
|
||||
private String name;
|
||||
|
||||
private Host host;
|
||||
|
||||
// ... getter and setters
|
||||
|
||||
public static class Host {
|
||||
|
||||
private String ip;
|
||||
|
||||
private int port;
|
||||
|
||||
// ... getter and setters
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
The preceding example produces metadata information for `server.name`, `server.host.ip`, and `server.host.port` properties.
|
||||
You can use the `@NestedConfigurationProperty` annotation on a field to indicate that a regular (non-inner) class should be treated as if it were nested.
|
||||
|
||||
TIP: This has no effect on collections and maps, as those types are automatically identified, and a single metadata property is generated for each of them.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.annotation-processor.adding-additional-metadata]]
|
||||
=== Adding Additional Metadata
|
||||
Spring Boot's configuration file handling is quite flexible, and it is often the case that properties may exist that are not bound to a `@ConfigurationProperties` bean.
|
||||
You may also need to tune some attributes of an existing key.
|
||||
To support such cases and let you provide custom "hints", the annotation processor automatically merges items from `META-INF/additional-spring-configuration-metadata.json` into the main metadata file.
|
||||
|
||||
If you refer to a property that has been detected automatically, the description, default value, and deprecation information are overridden, if specified.
|
||||
If the manual property declaration is not identified in the current module, it is added as a new property.
|
||||
|
||||
The format of the `additional-spring-configuration-metadata.json` file is exactly the same as the regular `spring-configuration-metadata.json`.
|
||||
The additional properties file is optional.
|
||||
If you do not have any additional properties, do not add the file.
|
||||
|
|
@ -0,0 +1,311 @@
|
|||
[[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:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"groups": [
|
||||
{
|
||||
"name": "server",
|
||||
"type": "org.springframework.boot.autoconfigure.web.ServerProperties",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
|
||||
},
|
||||
{
|
||||
"name": "spring.jpa.hibernate",
|
||||
"type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties",
|
||||
"sourceMethod": "getHibernate()"
|
||||
}
|
||||
...
|
||||
],"properties": [
|
||||
{
|
||||
"name": "server.port",
|
||||
"type": "java.lang.Integer",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
|
||||
},
|
||||
{
|
||||
"name": "server.address",
|
||||
"type": "java.net.InetAddress",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
|
||||
},
|
||||
{
|
||||
"name": "spring.jpa.hibernate.ddl-auto",
|
||||
"type": "java.lang.String",
|
||||
"description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.",
|
||||
"sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"
|
||||
}
|
||||
...
|
||||
],"hints": [
|
||||
{
|
||||
"name": "spring.jpa.hibernate.ddl-auto",
|
||||
"values": [
|
||||
{
|
||||
"value": "none",
|
||||
"description": "Disable DDL handling."
|
||||
},
|
||||
{
|
||||
"value": "validate",
|
||||
"description": "Validate the schema, make no changes to the database."
|
||||
},
|
||||
{
|
||||
"value": "update",
|
||||
"description": "Update the schema if necessary."
|
||||
},
|
||||
{
|
||||
"value": "create",
|
||||
"description": "Create the schema and destroy previous data."
|
||||
},
|
||||
{
|
||||
"value": "create-drop",
|
||||
"description": "Create and then destroy the schema at the end of the session."
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
Each "`property`" is a configuration item that the user specifies with a given value.
|
||||
For example, `server.port` and `server.address` might be specified in `application.properties`, as follows:
|
||||
|
||||
[source,properties,indent=0,configprops]
|
||||
----
|
||||
server.port=9090
|
||||
server.address=127.0.0.1
|
||||
----
|
||||
|
||||
The "`groups`" are higher level items that do not themselves specify a value but instead provide a contextual grouping for properties.
|
||||
For example, the `server.port` and `server.address` properties are part of the `server` group.
|
||||
|
||||
NOTE: It is not required that every "`property`" has a "`group`".
|
||||
Some properties might exist in their own right.
|
||||
|
||||
Finally, "`hints`" are additional information used to assist the user in configuring a given property.
|
||||
For example, when a developer is configuring the configprop:spring.jpa.hibernate.ddl-auto[] property, a tool can use the hints to offer some auto-completion help for the `none`, `validate`, `update`, `create`, and `create-drop` values.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.format.group]]
|
||||
=== Group Attributes
|
||||
The JSON object contained in the `groups` array can contain the attributes shown in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `name`
|
||||
| String
|
||||
| The full name of the group.
|
||||
This attribute is mandatory.
|
||||
|
||||
| `type`
|
||||
| String
|
||||
| The class name of the data type of the group.
|
||||
For example, if the group were based on a class annotated with `@ConfigurationProperties`, the attribute would contain the fully qualified name of that class.
|
||||
If it were based on a `@Bean` method, it would be the return type of that method.
|
||||
If the type is not known, the attribute may be omitted.
|
||||
|
||||
| `description`
|
||||
| String
|
||||
| A short description of the group that can be displayed to users.
|
||||
If no description is available, it may be omitted.
|
||||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||||
The last line in the description should end with a period (`.`).
|
||||
|
||||
| `sourceType`
|
||||
| String
|
||||
| The class name of the source that contributed this group.
|
||||
For example, if the group were based on a `@Bean` method annotated with `@ConfigurationProperties`, this attribute would contain the fully qualified name of the `@Configuration` class that contains the method.
|
||||
If the source type is not known, the attribute may be omitted.
|
||||
|
||||
| `sourceMethod`
|
||||
| String
|
||||
| The full name of the method (include parenthesis and argument types) that contributed this group (for example, the name of a `@ConfigurationProperties` annotated `@Bean` method).
|
||||
If the source method is not known, it may be omitted.
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.format.property]]
|
||||
=== Property Attributes
|
||||
The JSON object contained in the `properties` array can contain the attributes described in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `name`
|
||||
| String
|
||||
| The full name of the property.
|
||||
Names are in lower-case period-separated form (for example, `server.address`).
|
||||
This attribute is mandatory.
|
||||
|
||||
| `type`
|
||||
| String
|
||||
| The full signature of the data type of the property (for example, `java.lang.String`) but also a full generic type (such as `java.util.Map<java.lang.String,acme.MyEnum>`).
|
||||
You can use this attribute to guide the user as to the types of values that they can enter.
|
||||
For consistency, the type of a primitive is specified by using its wrapper counterpart (for example, `boolean` becomes `java.lang.Boolean`).
|
||||
Note that this class may be a complex type that gets converted from a `String` as values are bound.
|
||||
If the type is not known, it may be omitted.
|
||||
|
||||
| `description`
|
||||
| String
|
||||
| A short description of the property that can be displayed to users.
|
||||
If no description is available, it may be omitted.
|
||||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||||
The last line in the description should end with a period (`.`).
|
||||
|
||||
| `sourceType`
|
||||
| String
|
||||
| The class name of the source that contributed this property.
|
||||
For example, if the property were from a class annotated with `@ConfigurationProperties`, this attribute would contain the fully qualified name of that class.
|
||||
If the source type is unknown, it may be omitted.
|
||||
|
||||
| `defaultValue`
|
||||
| Object
|
||||
| The default value, which is used if the property is not specified.
|
||||
If the type of the property is an array, it can be an array of value(s).
|
||||
If the default value is unknown, it may be omitted.
|
||||
|
||||
| `deprecation`
|
||||
| Deprecation
|
||||
| Specify whether the property is deprecated.
|
||||
If the field is not deprecated or if that information is not known, it may be omitted.
|
||||
The next table offers more detail about the `deprecation` attribute.
|
||||
|===
|
||||
|
||||
The JSON object contained in the `deprecation` attribute of each `properties` element can contain the following attributes:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `level`
|
||||
| String
|
||||
| The level of deprecation, which can be either `warning` (the default) or `error`.
|
||||
When a property has a `warning` deprecation level, it should still be bound in the environment.
|
||||
However, when it has an `error` deprecation level, the property is no longer managed and is not bound.
|
||||
|
||||
| `reason`
|
||||
| String
|
||||
| A short description of the reason why the property was deprecated.
|
||||
If no reason is available, it may be omitted.
|
||||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||||
The last line in the description should end with a period (`.`).
|
||||
|
||||
| `replacement`
|
||||
| String
|
||||
| The full name of the property that _replaces_ this deprecated property.
|
||||
If there is no replacement for this property, it may be omitted.
|
||||
|===
|
||||
|
||||
NOTE: Prior to Spring Boot 1.3, a single `deprecated` boolean attribute can be used instead of the `deprecation` element.
|
||||
This is still supported in a deprecated fashion and should no longer be used.
|
||||
If no reason and replacement are available, an empty `deprecation` object should be set.
|
||||
|
||||
Deprecation can also be specified declaratively in code by adding the `@DeprecatedConfigurationProperty` annotation to the getter exposing the deprecated property.
|
||||
For instance, assume that the `app.acme.target` property was confusing and was renamed to `app.acme.name`.
|
||||
The following example shows how to handle that situation:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
@ConfigurationProperties("app.acme")
|
||||
public class AcmeProperties {
|
||||
|
||||
private String name;
|
||||
|
||||
public String getName() { ... }
|
||||
|
||||
public void setName(String name) { ... }
|
||||
|
||||
@DeprecatedConfigurationProperty(replacement = "app.acme.name")
|
||||
@Deprecated
|
||||
public String getTarget() {
|
||||
return getName();
|
||||
}
|
||||
|
||||
@Deprecated
|
||||
public void setTarget(String target) {
|
||||
setName(target);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
NOTE: There is no way to set a `level`.
|
||||
`warning` is always assumed, since code is still handling the property.
|
||||
|
||||
The preceding code makes sure that the deprecated property still works (delegating to the `name` property behind the scenes).
|
||||
Once the `getTarget` and `setTarget` methods can be removed from your public API, the automatic deprecation hint in the metadata goes away as well.
|
||||
If you want to keep a hint, adding manual metadata with an `error` deprecation level ensures that users are still informed about that property.
|
||||
Doing so is particularly useful when a `replacement` is provided.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.format.hints]]
|
||||
=== Hint Attributes
|
||||
The JSON object contained in the `hints` array can contain the attributes shown in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `name`
|
||||
| String
|
||||
| The full name of the property to which this hint refers.
|
||||
Names are in lower-case period-separated form (such as `spring.mvc.servlet.path`).
|
||||
If the property refers to a map (such as `system.contexts`), the hint either applies to the _keys_ of the map (`system.contexts.keys`) or the _values_ (`system.contexts.values`) of the map.
|
||||
This attribute is mandatory.
|
||||
|
||||
| `values`
|
||||
| ValueHint[]
|
||||
| A list of valid values as defined by the `ValueHint` object (described in the next table).
|
||||
Each entry defines the value and may have a description.
|
||||
|
||||
| `providers`
|
||||
| ValueProvider[]
|
||||
| A list of providers as defined by the `ValueProvider` object (described later in this document).
|
||||
Each entry defines the name of the provider and its parameters, if any.
|
||||
|===
|
||||
|
||||
The JSON object contained in the `values` attribute of each `hint` element can contain the attributes described in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
| Name | Type | Purpose
|
||||
|
||||
| `value`
|
||||
| Object
|
||||
| A valid value for the element to which the hint refers.
|
||||
If the type of the property is an array, it can also be an array of value(s).
|
||||
This attribute is mandatory.
|
||||
|
||||
| `description`
|
||||
| String
|
||||
| A short description of the value that can be displayed to users.
|
||||
If no description is available, it may be omitted.
|
||||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||||
The last line in the description should end with a period (`.`).
|
||||
|===
|
||||
|
||||
The JSON object contained in the `providers` attribute of each `hint` element can contain the attributes described in the following table:
|
||||
|
||||
[cols="1,1,4"]
|
||||
|===
|
||||
|Name | Type |Purpose
|
||||
|
||||
| `name`
|
||||
| String
|
||||
| The name of the provider to use to offer additional content assistance for the element to which the hint refers.
|
||||
|
||||
| `parameters`
|
||||
| JSON object
|
||||
| Any additional parameter that the provider supports (check the documentation of the provider for more details).
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
While the same names appearing in the metadata multiple times should not be common, consumers of metadata should take care to ensure that they support it.
|
||||
|
|
@ -0,0 +1,374 @@
|
|||
[[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:
|
||||
|
||||
* Describes the list of potential values for a property.
|
||||
* Associates a provider, to attach a well defined semantic to a property, so that a tool can discover the list of potential values based on the project's context.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.manual-hints.value-hint]]
|
||||
=== Value Hint
|
||||
The `name` attribute of each hint refers to the `name` of a property.
|
||||
In the <<configuration-metadata#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).
|
||||
The special `.keys` and `.values` suffixes must refer to the keys and the values, respectively.
|
||||
|
||||
Assume a `sample.contexts` maps magic `String` values to an integer, as shown in the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
@ConfigurationProperties("sample")
|
||||
public class SampleProperties {
|
||||
|
||||
private Map<String,Integer> contexts;
|
||||
// getters and setters
|
||||
}
|
||||
----
|
||||
|
||||
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#configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "sample.contexts.keys",
|
||||
"values": [
|
||||
{
|
||||
"value": "sample1"
|
||||
},
|
||||
{
|
||||
"value": "sample2"
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
TIP: We recommend that you use an `Enum` for those two values instead.
|
||||
If your IDE supports it, this is by far the most effective approach to auto-completion.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.manual-hints.value-providers]]
|
||||
=== Value Providers
|
||||
Providers are a powerful way to attach semantics to a property.
|
||||
In this section, we define the official providers that you can use for your own hints.
|
||||
However, your favorite IDE may implement some of these or none of them.
|
||||
Also, it could eventually provide its own.
|
||||
|
||||
NOTE: As this is a new feature, IDE vendors must catch up with how it works.
|
||||
Adoption times naturally vary.
|
||||
|
||||
The following table summarizes the list of supported providers:
|
||||
|
||||
[cols="2,4"]
|
||||
|===
|
||||
| Name | Description
|
||||
|
||||
| `any`
|
||||
| Permits any additional value to be provided.
|
||||
|
||||
| `class-reference`
|
||||
| Auto-completes the classes available in the project.
|
||||
Usually constrained by a base class that is specified by the `target` parameter.
|
||||
|
||||
| `handle-as`
|
||||
| Handles the property as if it were defined by the type defined by the mandatory `target` parameter.
|
||||
|
||||
| `logger-name`
|
||||
| Auto-completes valid logger names and <<features#features.logging.log-groups,logger groups>>.
|
||||
Typically, package and class names available in the current project can be auto-completed as well as defined groups.
|
||||
|
||||
| `spring-bean-reference`
|
||||
| Auto-completes the available bean names in the current project.
|
||||
Usually constrained by a base class that is specified by the `target` parameter.
|
||||
|
||||
| `spring-profile-name`
|
||||
| Auto-completes the available Spring profile names in the project.
|
||||
|===
|
||||
|
||||
TIP: Only one provider can be active for a given property, but you can specify several providers if they can all manage the property _in some way_.
|
||||
Make sure to place the most powerful provider first, as the IDE must use the first one in the JSON section that it can handle.
|
||||
If no provider for a given property is supported, no special content assistance is provided, either.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.manual-hints.value-providers.any]]
|
||||
==== Any
|
||||
The special **any** provider value permits any additional values to be provided.
|
||||
Regular value validation based on the property type should be applied if this is supported.
|
||||
|
||||
This provider is typically used if you have a list of values and any extra values should still be considered as valid.
|
||||
|
||||
The following example offers `on` and `off` as auto-completion values for `system.state`:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "system.state",
|
||||
"values": [
|
||||
{
|
||||
"value": "on"
|
||||
},
|
||||
{
|
||||
"value": "off"
|
||||
}
|
||||
],
|
||||
"providers": [
|
||||
{
|
||||
"name": "any"
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
Note that, in the preceding example, any other value is also allowed.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.manual-hints.value-providers.class-reference]]
|
||||
==== Class Reference
|
||||
The **class-reference** provider auto-completes classes available in the project.
|
||||
This provider supports the following parameters:
|
||||
|
||||
[cols="1,1,2,4"]
|
||||
|===
|
||||
| Parameter | Type | Default value | Description
|
||||
|
||||
| `target`
|
||||
| `String` (`Class`)
|
||||
| _none_
|
||||
| The fully qualified name of the class that should be assignable to the chosen value.
|
||||
Typically used to filter out-non candidate classes.
|
||||
Note that this information can be provided by the type itself by exposing a class with the appropriate upper bound.
|
||||
|
||||
| `concrete`
|
||||
| `boolean`
|
||||
| true
|
||||
| Specify whether only concrete classes are to be considered as valid candidates.
|
||||
|===
|
||||
|
||||
|
||||
The following metadata snippet corresponds to the standard `server.servlet.jsp.class-name` property that defines the `JspServlet` class name to use:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "server.servlet.jsp.class-name",
|
||||
"providers": [
|
||||
{
|
||||
"name": "class-reference",
|
||||
"parameters": {
|
||||
"target": "javax.servlet.http.HttpServlet"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.manual-hints.value-providers.handle-as]]
|
||||
==== Handle As
|
||||
The **handle-as** provider lets you substitute the type of the property to a more high-level type.
|
||||
This typically happens when the property has a `java.lang.String` type, because you do not want your configuration classes to rely on classes that may not be on the classpath.
|
||||
This provider supports the following parameters:
|
||||
|
||||
[cols="1,1,2,4"]
|
||||
|===
|
||||
| Parameter | Type | Default value | Description
|
||||
|
||||
| **`target`**
|
||||
| `String` (`Class`)
|
||||
| _none_
|
||||
| The fully qualified name of the type to consider for the property.
|
||||
This parameter is mandatory.
|
||||
|===
|
||||
|
||||
The following types can be used:
|
||||
|
||||
* Any `java.lang.Enum`: Lists the possible values for the property.
|
||||
(We recommend defining the property with the `Enum` type, as no further hint should be required for the IDE to auto-complete the values)
|
||||
* `java.nio.charset.Charset`: Supports auto-completion of charset/encoding values (such as `UTF-8`)
|
||||
* `java.util.Locale`: auto-completion of locales (such as `en_US`)
|
||||
* `org.springframework.util.MimeType`: Supports auto-completion of content type values (such as `text/plain`)
|
||||
* `org.springframework.core.io.Resource`: Supports auto-completion of Spring’s Resource abstraction to refer to a file on the filesystem or on the classpath (such as `classpath:/sample.properties`)
|
||||
|
||||
TIP: If multiple values can be provided, use a `Collection` or _Array_ type to teach the IDE about it.
|
||||
|
||||
The following metadata snippet corresponds to the standard `spring.liquibase.change-log` property that defines the path to the changelog to use.
|
||||
It is actually used internally as a `org.springframework.core.io.Resource` but cannot be exposed as such, because we need to keep the original String value to pass it to the Liquibase API.
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "spring.liquibase.change-log",
|
||||
"providers": [
|
||||
{
|
||||
"name": "handle-as",
|
||||
"parameters": {
|
||||
"target": "org.springframework.core.io.Resource"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.manual-hints.value-providers.logger-name]]
|
||||
==== Logger Name
|
||||
The **logger-name** provider auto-completes valid logger names and <<features#features.logging.log-groups,logger groups>>.
|
||||
Typically, package and class names available in the current project can be auto-completed.
|
||||
If groups are enabled (default) and if a custom logger group is identified in the configuration, auto-completion for it should be provided.
|
||||
Specific frameworks may have extra magic logger names that can be supported as well.
|
||||
|
||||
This provider supports the following parameters:
|
||||
|
||||
[cols="1,1,2,4"]
|
||||
|===
|
||||
| Parameter | Type | Default value | Description
|
||||
|
||||
| `group`
|
||||
| `boolean`
|
||||
| `true`
|
||||
| Specify whether known groups should be considered.
|
||||
|===
|
||||
|
||||
Since a logger name can be any arbitrary name, this provider should allow any value but could highlight valid package and class names that are not available in the project's classpath.
|
||||
|
||||
The following metadata snippet corresponds to the standard `logging.level` property.
|
||||
Keys are _logger names_, and values correspond to the standard log levels or any custom level.
|
||||
As Spring Boot defines a few logger groups out-of-the-box, dedicated value hints have been added for those.
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "logging.level.keys",
|
||||
"values": [
|
||||
{
|
||||
"value": "root",
|
||||
"description": "Root logger used to assign the default logging level."
|
||||
},
|
||||
{
|
||||
"value": "sql",
|
||||
"description": "SQL logging group including Hibernate SQL logger."
|
||||
},
|
||||
{
|
||||
"value": "web",
|
||||
"description": "Web logging group including codecs."
|
||||
}
|
||||
],
|
||||
"providers": [
|
||||
{
|
||||
"name": "logger-name"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "logging.level.values",
|
||||
"values": [
|
||||
{
|
||||
"value": "trace"
|
||||
},
|
||||
{
|
||||
"value": "debug"
|
||||
},
|
||||
{
|
||||
"value": "info"
|
||||
},
|
||||
{
|
||||
"value": "warn"
|
||||
},
|
||||
{
|
||||
"value": "error"
|
||||
},
|
||||
{
|
||||
"value": "fatal"
|
||||
},
|
||||
{
|
||||
"value": "off"
|
||||
}
|
||||
|
||||
],
|
||||
"providers": [
|
||||
{
|
||||
"name": "any"
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.manual-hints.value-providers.spring-bean-reference]]
|
||||
==== Spring Bean Reference
|
||||
The **spring-bean-reference** provider auto-completes the beans that are defined in the configuration of the current project.
|
||||
This provider supports the following parameters:
|
||||
|
||||
[cols="1,1,2,4"]
|
||||
|===
|
||||
| Parameter | Type | Default value | Description
|
||||
|
||||
| `target`
|
||||
| `String` (`Class`)
|
||||
| _none_
|
||||
| The fully qualified name of the bean class that should be assignable to the candidate.
|
||||
Typically used to filter out non-candidate beans.
|
||||
|===
|
||||
|
||||
The following metadata snippet corresponds to the standard `spring.jmx.server` property that defines the name of the `MBeanServer` bean to use:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "spring.jmx.server",
|
||||
"providers": [
|
||||
{
|
||||
"name": "spring-bean-reference",
|
||||
"parameters": {
|
||||
"target": "javax.management.MBeanServer"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
||||
NOTE: The binder is not aware of the metadata.
|
||||
If you provide that hint, you still need to transform the bean name into an actual Bean reference using by the `ApplicationContext`.
|
||||
|
||||
|
||||
|
||||
[[configuration-metadata.manual-hints.value-providers.spring-profile-name]]
|
||||
==== Spring Profile Name
|
||||
The **spring-profile-name** provider auto-completes the Spring profiles that are defined in the configuration of the current project.
|
||||
|
||||
The following metadata snippet corresponds to the standard `spring.profiles.active` property that defines the name of the Spring profile(s) to enable:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
{"hints": [
|
||||
{
|
||||
"name": "spring.profiles.active",
|
||||
"providers": [
|
||||
{
|
||||
"name": "spring-profile-name"
|
||||
}
|
||||
]
|
||||
}
|
||||
]}
|
||||
----
|
||||
|
|
@ -1,27 +1,14 @@
|
|||
[appendix]
|
||||
[[appendix.dependency-versions]]
|
||||
= Dependency versions
|
||||
[[dependency-versions]]
|
||||
= Dependency Versions
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
This appendix provides details of the dependencies that are managed by Spring Boot.
|
||||
|
||||
|
||||
|
||||
[[appendix.dependency-versions.coordinates]]
|
||||
== Managed Dependency Coordinates
|
||||
include::dependency-versions/coordinates.adoc[]
|
||||
|
||||
The following table provides details of all of the dependency versions that are provided by Spring Boot in its CLI (Command Line Interface), Maven dependency management, and Gradle plugin.
|
||||
When you declare a dependency on one of these artifacts without declaring a version, the version listed in the table is used.
|
||||
|
||||
include::generated-dependency-versions.adoc[]
|
||||
|
||||
|
||||
|
||||
[[appendix.dependency-versions.properties]]
|
||||
== Version Properties
|
||||
|
||||
The following table provides all properties that can be used to override the versions managed by Spring Boot.
|
||||
Browse the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/build.gradle[`spring-boot-dependencies` build.gradle] for a complete list of dependencies.
|
||||
You can learn how to customize these versions in your application in the <<build-tool-plugins.adoc#build-tool-plugins,Build Tool Plugins documentation>>.
|
||||
|
||||
include::generated-version-properties.adoc[]
|
||||
include::dependency-versions/properties.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
[[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.
|
||||
When you declare a dependency on one of these artifacts without declaring a version, the version listed in the table is used.
|
||||
|
||||
include::documented-coordinates.adoc[]
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
[[dependency-versions.properties]]
|
||||
== Version Properties
|
||||
|
||||
The following table provides all properties that can be used to override the versions managed by Spring Boot.
|
||||
Browse the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/build.gradle[`spring-boot-dependencies` build.gradle] for a complete list of dependencies.
|
||||
You can learn how to customize these versions in your application in the <<build-tool-plugins#build-tool-plugins,Build Tool Plugins documentation>>.
|
||||
|
||||
include::documented-properties.adoc[]
|
||||
|
|
@ -2,6 +2,8 @@
|
|||
= Deploying Spring Boot Applications
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
Spring Boot's flexible packaging options provide a great deal of choice when it comes to deploying your application.
|
||||
You can deploy Spring Boot applications to a variety of cloud platforms, to container images (such as Docker), or to virtual/real machines.
|
||||
|
||||
|
|
@ -9,851 +11,10 @@ This section covers some of the more common deployment scenarios.
|
|||
|
||||
|
||||
|
||||
[[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.
|
||||
For example, Cloud Foundry operates this way.
|
||||
One way to run an unpacked archive is by starting the appropriate launcher, as follows:
|
||||
include::deployment/containers.adoc[]
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ jar -xf myapp.jar
|
||||
$ java org.springframework.boot.loader.JarLauncher
|
||||
----
|
||||
include::deployment/cloud.adoc[]
|
||||
|
||||
This is actually slightly faster on startup (depending on the size of the jar) than running from an unexploded archive.
|
||||
At runtime you shouldn't expect any differences.
|
||||
include::deployment/installing.adoc[]
|
||||
|
||||
Once you have unpacked the jar file, you can also get an extra boost to startup time by running the app with its "natural" main method instead of the `JarLauncher`. For example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ jar -xf myapp.jar
|
||||
$ java -cp BOOT-INF/classes:BOOT-INF/lib/* com.example.MyApplication
|
||||
----
|
||||
|
||||
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 <<features.adoc#features.container-images.building.dockerfiles,creating separate layers>> for your dependencies and application classes and resources (which normally change more frequently).
|
||||
|
||||
|
||||
|
||||
[[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`".
|
||||
They manage application processes (not Java applications 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`, 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
You can deploy stand-alone executable jar applications as well as traditional `.war` packaged applications.
|
||||
|
||||
Once you have built your application (by using, for example, `mvn clean package`) and have https://docs.cloudfoundry.org/cf-cli/install-go-cli.html[installed the `cf` command line tool], deploy your application by using the `cf push` command, substituting the path to your compiled `.jar`.
|
||||
Be sure to have https://docs.cloudfoundry.org/cf-cli/getting-started.html#login[logged in with your `cf` command line client] before pushing an application.
|
||||
The following line shows using the `cf push` command to deploy an application:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ cf push acloudyspringtime -p target/demo-0.0.1-SNAPSHOT.jar
|
||||
----
|
||||
|
||||
NOTE: In the preceding example, we substitute `acloudyspringtime` for whatever value you give `cf` as the name of your application.
|
||||
|
||||
See the https://docs.cloudfoundry.org/cf-cli/getting-started.html#push[`cf push` documentation] for more options.
|
||||
If there is a Cloud Foundry https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html[`manifest.yml`] file present in the same directory, it is considered.
|
||||
|
||||
At this point, `cf` starts uploading your application, producing output similar to the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
Uploading acloudyspringtime... *OK*
|
||||
Preparing to start acloudyspringtime... *OK*
|
||||
-----> Downloaded app package (*8.9M*)
|
||||
-----> Java Buildpack Version: v3.12 (offline) | https://github.com/cloudfoundry/java-buildpack.git#6f25b7e
|
||||
-----> Downloading Open Jdk JRE 1.8.0_121 from https://java-buildpack.cloudfoundry.org/openjdk/trusty/x86_64/openjdk-1.8.0_121.tar.gz (found in cache)
|
||||
Expanding Open Jdk JRE to .java-buildpack/open_jdk_jre (1.6s)
|
||||
-----> Downloading Open JDK Like Memory Calculator 2.0.2_RELEASE from https://java-buildpack.cloudfoundry.org/memory-calculator/trusty/x86_64/memory-calculator-2.0.2_RELEASE.tar.gz (found in cache)
|
||||
Memory Settings: -Xss349K -Xmx681574K -XX:MaxMetaspaceSize=104857K -Xms681574K -XX:MetaspaceSize=104857K
|
||||
-----> Downloading Container Certificate Trust Store 1.0.0_RELEASE from https://java-buildpack.cloudfoundry.org/container-certificate-trust-store/container-certificate-trust-store-1.0.0_RELEASE.jar (found in cache)
|
||||
Adding certificates to .java-buildpack/container_certificate_trust_store/truststore.jks (0.6s)
|
||||
-----> Downloading Spring Auto Reconfiguration 1.10.0_RELEASE from https://java-buildpack.cloudfoundry.org/auto-reconfiguration/auto-reconfiguration-1.10.0_RELEASE.jar (found in cache)
|
||||
Checking status of app 'acloudyspringtime'...
|
||||
0 of 1 instances running (1 starting)
|
||||
...
|
||||
0 of 1 instances running (1 starting)
|
||||
...
|
||||
0 of 1 instances running (1 starting)
|
||||
...
|
||||
1 of 1 instances running (1 running)
|
||||
|
||||
App started
|
||||
----
|
||||
|
||||
Congratulations! The application is now live!
|
||||
|
||||
Once your application is live, you can verify the status of the deployed application by using the `cf apps` command, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ cf apps
|
||||
Getting applications in ...
|
||||
OK
|
||||
|
||||
name requested state instances memory disk urls
|
||||
...
|
||||
acloudyspringtime started 1/1 512M 1G acloudyspringtime.cfapps.io
|
||||
...
|
||||
----
|
||||
|
||||
Once Cloud Foundry acknowledges that your application has been deployed, you should be able to find the application at the URI given.
|
||||
In the preceding example, you could find it at `\https://acloudyspringtime.cfapps.io/`.
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.cloud-foundry.binding-to-services]]
|
||||
==== Binding to Services
|
||||
By default, metadata about the running application as well as service connection information is exposed to the application as environment variables (for example: `$VCAP_SERVICES`).
|
||||
This architecture decision is due to Cloud Foundry's polyglot (any language and platform can be supported as a buildpack) nature.
|
||||
Process-scoped environment variables are language agnostic.
|
||||
|
||||
Environment variables do not always make for the easiest API, so Spring Boot automatically extracts them and flattens the data into properties that can be accessed through Spring's `Environment` abstraction, as shown in the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
@Component
|
||||
class MyBean implements EnvironmentAware {
|
||||
|
||||
private String instanceId;
|
||||
|
||||
@Override
|
||||
public void setEnvironment(Environment environment) {
|
||||
this.instanceId = environment.getProperty("vcap.application.instance_id");
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
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 the {spring-boot-module-api}/cloud/CloudFoundryVcapEnvironmentPostProcessor.html['`CloudFoundryVcapEnvironmentPostProcessor`'] Javadoc for complete details.
|
||||
|
||||
TIP: The https://github.com/pivotal-cf/java-cfenv/[Java CFEnv] project is a better fit for tasks such as configuring a DataSource.
|
||||
|
||||
|
||||
|
||||
[[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 <<features.adoc#features.spring-application.application-availability,manage the state of your application>> and export it with <<actuator.adoc#actuator.endpoints.kubernetes-probes, HTTP Kubernetes Probes using Actuator>>.
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.kubernetes.container-lifecycle]]
|
||||
==== Kubernetes Container Lifecycle
|
||||
When Kubernetes deletes an application instance, the shutdown process involves several subsystems concurrently: shutdown hooks, unregistering the service, removing the instance from the load-balancer...
|
||||
Because this shutdown processing happens in parallel (and due to the nature of distributed systems), there is a window during which traffic can be routed to a pod that has also begun its shutdown processing.
|
||||
|
||||
You can configure a sleep execution in a preStop handler to avoid requests being routed to a pod that has already begun shutting down.
|
||||
This sleep should be long enough for new requests to stop being routed to the pod and its duration will vary from deployment to deployment.
|
||||
The preStop handler can be configured via the PodSpec in the pod's configuration file as follows:
|
||||
|
||||
[source,yml,indent=0]
|
||||
----
|
||||
spec:
|
||||
containers:
|
||||
- name: example-container
|
||||
image: example-image
|
||||
lifecycle:
|
||||
preStop:
|
||||
exec:
|
||||
command: ["sh", "-c", "sleep 10"]
|
||||
----
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
Heroku assigns a `port` for the Java application to use and then ensures that routing to the external URI works.
|
||||
|
||||
You must configure your application to listen on the correct port.
|
||||
The following example shows the `Procfile` for our starter REST application:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
web: java -Dserver.port=$PORT -jar target/demo-0.0.1-SNAPSHOT.jar
|
||||
----
|
||||
|
||||
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` environment variable is assigned to us by the Heroku PaaS.
|
||||
|
||||
This should be everything you need.
|
||||
The most common deployment workflow for Heroku deployments is to `git push` the code to production, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ git push heroku main
|
||||
|
||||
Initializing repository, *done*.
|
||||
Counting objects: 95, *done*.
|
||||
Delta compression using up to 8 threads.
|
||||
Compressing objects: 100% (78/78), *done*.
|
||||
Writing objects: 100% (95/95), 8.66 MiB | 606.00 KiB/s, *done*.
|
||||
Total 95 (delta 31), reused 0 (delta 0)
|
||||
|
||||
-----> Java app detected
|
||||
-----> Installing OpenJDK 1.8... *done*
|
||||
-----> Installing Maven 3.3.1... *done*
|
||||
-----> Installing settings.xml... *done*
|
||||
-----> Executing: mvn -B -DskipTests=true clean install
|
||||
|
||||
[INFO] Scanning for projects...
|
||||
Downloading: https://repo.spring.io/...
|
||||
Downloaded: https://repo.spring.io/... (818 B at 1.8 KB/sec)
|
||||
....
|
||||
Downloaded: https://s3pository.heroku.com/jvm/... (152 KB at 595.3 KB/sec)
|
||||
[INFO] Installing /tmp/build_0c35a5d2-a067-4abc-a232-14b1fb7a8229/target/...
|
||||
[INFO] Installing /tmp/build_0c35a5d2-a067-4abc-a232-14b1fb7a8229/pom.xml ...
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] *BUILD SUCCESS*
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] Total time: 59.358s
|
||||
[INFO] Finished at: Fri Mar 07 07:28:25 UTC 2014
|
||||
[INFO] Final Memory: 20M/493M
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
|
||||
-----> Discovering process types
|
||||
Procfile declares types -> *web*
|
||||
|
||||
-----> Compressing... *done*, 70.4MB
|
||||
-----> Launching... *done*, v6
|
||||
https://agile-sierra-1405.herokuapp.com/ *deployed to Heroku*
|
||||
|
||||
To git@heroku.com:agile-sierra-1405.git
|
||||
* [new branch] main -> main
|
||||
----
|
||||
|
||||
Your application should now be up and running on Heroku.
|
||||
For more details, refer to https://devcenter.heroku.com/articles/deploying-spring-boot-apps-to-heroku[Deploying Spring Boot Applications to Heroku].
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.openshift]]
|
||||
=== OpenShift
|
||||
https://www.openshift.com/[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]
|
||||
* https://blog.openshift.com/using-spring-boot-on-openshift/[Running as a traditional web application on Wildfly]
|
||||
* https://blog.openshift.com/openshift-commons-briefing-96-cloud-native-applications-spring-rhoar/[OpenShift Commons Briefing]
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
* AWS Elastic Beanstalk
|
||||
* AWS Code Deploy
|
||||
* AWS OPS Works
|
||||
* AWS Cloud Formation
|
||||
* AWS Container Registry
|
||||
|
||||
Each has different features and pricing models.
|
||||
In this document, we describe to approach using AWS Elastic 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`".
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.aws.beanstalk.tomcat-platform]]
|
||||
===== Using the Tomcat Platform
|
||||
This option applies to Spring Boot projects that produce a war file.
|
||||
No special configuration is required.
|
||||
You need only follow the official guide.
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.aws.beanstalk.java-se-platform]]
|
||||
===== Using the Java SE Platform
|
||||
This option applies to Spring Boot projects that produce a jar file and run an embedded web container.
|
||||
Elastic Beanstalk environments run an nginx instance on port 80 to proxy the actual application, running on port 5000.
|
||||
To configure it, add the following line to your `application.properties` file:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
server.port=5000
|
||||
----
|
||||
|
||||
|
||||
[TIP]
|
||||
.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 lines similar to the following to your `.elasticbeanstalk/config.yml` file:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
deploy:
|
||||
artifact: target/demo-0.0.1-SNAPSHOT.jar
|
||||
----
|
||||
====
|
||||
|
||||
[TIP]
|
||||
.Reduce costs by setting the environment type
|
||||
====
|
||||
By default an Elastic Beanstalk environment is load balanced.
|
||||
The load balancer has a significant cost.
|
||||
To avoid that cost, set the environment type to "`Single instance`", as described in https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html#environments-create-wizard-capacity[the Amazon documentation].
|
||||
You can also create single instance environments by using the CLI and the following command:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
eb create -s
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
Boxfuse leverages this information both for the images it produces as well as for all the resources it provisions (instances, security groups, elastic load balancers, and so on).
|
||||
|
||||
Once you have created a https://console.boxfuse.com[Boxfuse account], connected it to your AWS account, installed the latest version of the Boxfuse Client, and ensured that the application has been built by Maven or Gradle (by using, for example, `mvn clean package`), you can deploy your Spring Boot application to AWS with a command similar to the following:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ boxfuse run myapp-1.0.jar -env=prod
|
||||
----
|
||||
|
||||
See the https://boxfuse.com/docs/commandline/run.html[`boxfuse run` documentation] for more options.
|
||||
If there is a https://boxfuse.com/docs/commandline/#configuration[`boxfuse.conf`] file present in the current directory, it is considered.
|
||||
|
||||
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 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 example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
Fusing Image for myapp-1.0.jar ...
|
||||
Image fused in 00:06.838s (53937 K) -> axelfontaine/myapp:1.0
|
||||
Creating axelfontaine/myapp ...
|
||||
Pushing axelfontaine/myapp:1.0 ...
|
||||
Verifying axelfontaine/myapp:1.0 ...
|
||||
Creating Elastic IP ...
|
||||
Mapping myapp-axelfontaine.boxfuse.io to 52.28.233.167 ...
|
||||
Waiting for AWS to create an AMI for axelfontaine/myapp:1.0 in eu-central-1 (this may take up to 50 seconds) ...
|
||||
AMI created in 00:23.557s -> ami-d23f38cf
|
||||
Creating security group boxfuse-sg_axelfontaine/myapp:1.0 ...
|
||||
Launching t2.micro instance of axelfontaine/myapp:1.0 (ami-d23f38cf) in eu-central-1 ...
|
||||
Instance launched in 00:30.306s -> i-92ef9f53
|
||||
Waiting for AWS to boot Instance i-92ef9f53 and Payload to start at https://52.28.235.61/ ...
|
||||
Payload started in 00:29.266s -> https://52.28.235.61/
|
||||
Remapping Elastic IP 52.28.233.167 to i-92ef9f53 ...
|
||||
Waiting 15s for AWS to complete Elastic IP Zero Downtime transition ...
|
||||
Deployment completed successfully. axelfontaine/myapp:1.0 is up and running at https://myapp-axelfontaine.boxfuse.io/
|
||||
----
|
||||
|
||||
Your application should now be up and running on AWS.
|
||||
|
||||
See the blog post on https://boxfuse.com/blog/spring-boot-ec2.html[deploying Spring Boot apps on EC2] as well as the https://boxfuse.com/docs/payloads/springboot.html[documentation for the Boxfuse Spring Boot integration] to get started with a Maven build to run the app.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
To run in App Engine, you can create a project in the UI first, which sets up a unique identifier for you and also sets up HTTP routes.
|
||||
Add a Java app to the project and leave it empty and then use the https://cloud.google.com/sdk/install[Google Cloud SDK] to push your Spring Boot app into that slot from the command line or CI build.
|
||||
|
||||
App Engine Standard requires you to use WAR packaging.
|
||||
Follow https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/appengine-java8/springboot-helloworld/README.md[these steps] to deploy App Engine Standard application to Google Cloud.
|
||||
|
||||
Alternatively, App Engine Flex requires 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 following file:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
service: default
|
||||
|
||||
runtime: java
|
||||
env: flex
|
||||
|
||||
runtime_config:
|
||||
jdk: openjdk8
|
||||
|
||||
handlers:
|
||||
- url: /.*
|
||||
script: this field is required, but ignored
|
||||
|
||||
manual_scaling:
|
||||
instances: 1
|
||||
|
||||
health_check:
|
||||
enable_health_check: False
|
||||
|
||||
env_variables:
|
||||
ENCRYPT_KEY: your_encryption_key_here
|
||||
----
|
||||
|
||||
You can deploy the app (for example, with a Maven plugin) by adding the project ID to the build configuration, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>com.google.cloud.tools</groupId>
|
||||
<artifactId>appengine-maven-plugin</artifactId>
|
||||
<version>1.3.0</version>
|
||||
<configuration>
|
||||
<project>myproject</project>
|
||||
</configuration>
|
||||
</plugin>
|
||||
----
|
||||
|
||||
Then deploy with `mvn appengine:deploy` (if you need to authenticate first, the build fails).
|
||||
|
||||
|
||||
|
||||
[[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.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.
|
||||
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 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.
|
||||
|
||||
CAUTION: A zip64-format jar file cannot be made fully executable.
|
||||
Attempting to do so will result in a jar file that is reported as corrupt when executed directly or with `java -jar`.
|
||||
A standard-format jar file that contains one or more zip64-format nested jars can be fully executable.
|
||||
|
||||
To create a '`fully executable`' jar with Maven, use the following plugin configuration:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<configuration>
|
||||
<executable>true</executable>
|
||||
</configuration>
|
||||
</plugin>
|
||||
----
|
||||
|
||||
The following example shows the equivalent Gradle configuration:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
bootJar {
|
||||
launchScript()
|
||||
}
|
||||
----
|
||||
|
||||
You can then run your application by typing `./my-application.jar` (where `my-application` is the name of your artifact).
|
||||
The directory containing the jar is used as your application's working directory.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.supported-operating-systems]]
|
||||
=== Supported Operating Systems
|
||||
The default script supports most Linux distributions and is tested on CentOS and Ubuntu.
|
||||
Other platforms, such as OS X and FreeBSD, require the use of a custom `embeddedLaunchScript`.
|
||||
|
||||
|
||||
|
||||
[[deployment.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.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.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:
|
||||
|
||||
* Starts the services as the user that owns the jar file
|
||||
* Tracks the application's PID by using `/var/run/<appname>/<appname>.pid`
|
||||
* Writes console logs to `/var/log/<appname>.log`
|
||||
|
||||
Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a Spring Boot application as an `init.d` service, create a symlink, as follows:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ sudo ln -s /var/myapp/myapp.jar /etc/init.d/myapp
|
||||
----
|
||||
|
||||
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:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ service myapp start
|
||||
----
|
||||
|
||||
TIP: If your application fails to start, check the log file written to `/var/log/<appname>.log` for errors.
|
||||
|
||||
You can also flag the application to start automatically by using your standard operating system tools.
|
||||
For example, on Debian, you could use the following command:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ update-rc.d myapp defaults <priority>
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.init-d.securing]]
|
||||
===== Securing an init.d Service
|
||||
NOTE: The following is a set of guidelines on how to secure a Spring Boot application that runs as an init.d service.
|
||||
It is not intended to be an exhaustive list of everything that should be done to harden an application and the environment in which it runs.
|
||||
|
||||
When executed as root, as is the case when root is being used to start an init.d service, the default executable script runs the application as the user specified in the `RUN_AS_USER` environment variable.
|
||||
When the environment variable is not set, the user who owns the jar file is used instead.
|
||||
You should never run a Spring Boot application as `root`, so `RUN_AS_USER` should never be root and your application's jar file should never be owned by root.
|
||||
Instead, create a specific user to run your application and set the `RUN_AS_USER` environment variable or use `chown` to make it the owner of the jar file, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ chown bootapp:bootapp your-app.jar
|
||||
----
|
||||
|
||||
In this case, the default executable script runs the application as the `bootapp` user.
|
||||
|
||||
TIP: To reduce the chances of the application's user account being compromised, you should consider preventing it from using a login shell.
|
||||
For example, you can set the account's shell to `/usr/sbin/nologin`.
|
||||
|
||||
You should also take steps to prevent the modification of your application's jar file.
|
||||
Firstly, configure its permissions so that it cannot be written and can only be read or executed by its owner, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ chmod 500 your-app.jar
|
||||
----
|
||||
|
||||
Second, you should also take steps to limit the damage if your application or the account that's running it is compromised.
|
||||
If an attacker does gain access, they could make the jar file writable and change its contents.
|
||||
One way to protect against this is to make it immutable by using `chattr`, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ sudo chattr +i your-app.jar
|
||||
----
|
||||
|
||||
This will prevent any user, including root, from modifying the jar.
|
||||
|
||||
If root is used to control the application's service and you <<deployment-script-customization-conf-file, use a `.conf` file>> to customize its startup, the `.conf` file is read and evaluated by the root user.
|
||||
It should be secured accordingly.
|
||||
Use `chmod` so that the file can only be read by the owner and use `chown` to make root the owner, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ chmod 400 your-app.conf
|
||||
$ sudo chown root:root your-app.conf
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a Spring Boot application as a `systemd` service, create a script named `myapp.service` and place it in `/etc/systemd/system` directory.
|
||||
The following script offers an example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
[Unit]
|
||||
Description=myapp
|
||||
After=syslog.target
|
||||
|
||||
[Service]
|
||||
User=myapp
|
||||
ExecStart=/var/myapp/myapp.jar
|
||||
SuccessExitStatus=143
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
----
|
||||
|
||||
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 the `run` command is used by default.
|
||||
|
||||
Note that, unlike when running as an `init.d` service, the user that runs the application, the PID file, and the console log file are managed by `systemd` itself and therefore must be configured by using appropriate fields in the '`service`' script.
|
||||
Consult the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
|
||||
|
||||
To flag the application to start automatically on system boot, use the following command:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ systemctl enable myapp.service
|
||||
----
|
||||
|
||||
Refer to `man systemctl` for more details.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization]]
|
||||
==== Customizing the Startup Script
|
||||
The default embedded startup script written by the Maven or Gradle plugin can be customized in a number of ways.
|
||||
For most people, using the default script along with a few customizations is usually enough.
|
||||
If you find you cannot customize something that you need to, use the `embeddedLaunchScript` option to write your own file entirely.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization.when-written]]
|
||||
===== Customizing the Start Script When It Is Written
|
||||
It often makes sense to customize elements of the start script as it is written into the jar file.
|
||||
For example, init.d scripts can provide a "`description`".
|
||||
Since you know the description up front (and it need not change), you may as well provide it when the jar is generated.
|
||||
|
||||
To customize written elements, use the `embeddedLaunchScriptProperties` option of the Spring Boot Maven plugin or the {spring-boot-gradle-plugin-docs}#packaging-executable-configuring-launch-script[`properties` property of the Spring Boot Gradle plugin's `launchScript`].
|
||||
|
||||
The following property substitutions are supported with the default script:
|
||||
|
||||
[cols="1,3,3,3"]
|
||||
|===
|
||||
| Name | Description | Gradle default | Maven default
|
||||
|
||||
| `mode`
|
||||
| The script mode.
|
||||
| `auto`
|
||||
| `auto`
|
||||
|
||||
| `initInfoProvides`
|
||||
| The `Provides` section of "`INIT INFO`"
|
||||
| `${task.baseName}`
|
||||
| `${project.artifactId}`
|
||||
|
||||
| `initInfoRequiredStart`
|
||||
| `Required-Start` section of "`INIT INFO`".
|
||||
| `$remote_fs $syslog $network`
|
||||
| `$remote_fs $syslog $network`
|
||||
|
||||
| `initInfoRequiredStop`
|
||||
| `Required-Stop` section of "`INIT INFO`".
|
||||
| `$remote_fs $syslog $network`
|
||||
| `$remote_fs $syslog $network`
|
||||
|
||||
| `initInfoDefaultStart`
|
||||
| `Default-Start` section of "`INIT INFO`".
|
||||
| `2 3 4 5`
|
||||
| `2 3 4 5`
|
||||
|
||||
| `initInfoDefaultStop`
|
||||
| `Default-Stop` section of "`INIT INFO`".
|
||||
| `0 1 6`
|
||||
| `0 1 6`
|
||||
|
||||
| `initInfoShortDescription`
|
||||
| `Short-Description` section of "`INIT INFO`".
|
||||
| Single-line version of `${project.description}` (falling back to `${task.baseName}`)
|
||||
| `${project.name}`
|
||||
|
||||
| `initInfoDescription`
|
||||
| `Description` section of "`INIT INFO`".
|
||||
| `${project.description}` (falling back to `${task.baseName}`)
|
||||
| `${project.description}` (falling back to `${project.name}`)
|
||||
|
||||
| `initInfoChkconfig`
|
||||
| `chkconfig` section of "`INIT INFO`"
|
||||
| `2345 99 01`
|
||||
| `2345 99 01`
|
||||
|
||||
| `confFolder`
|
||||
| The default value for `CONF_FOLDER`
|
||||
| Folder containing the jar
|
||||
| Folder containing the jar
|
||||
|
||||
| `inlinedConfScript`
|
||||
| Reference to a file script that should be inlined in the default launch script.
|
||||
This can be used to set environmental variables such as `JAVA_OPTS` before any external config files are loaded
|
||||
|
|
||||
|
|
||||
|
||||
| `logFolder`
|
||||
| Default value for `LOG_FOLDER`.
|
||||
Only valid for an `init.d` service
|
||||
|
|
||||
|
|
||||
|
||||
| `logFilename`
|
||||
| Default value for `LOG_FILENAME`.
|
||||
Only valid for an `init.d` service
|
||||
|
|
||||
|
|
||||
|
||||
| `pidFolder`
|
||||
| Default value for `PID_FOLDER`.
|
||||
Only valid for an `init.d` service
|
||||
|
|
||||
|
|
||||
|
||||
| `pidFilename`
|
||||
| Default value for the name of the PID file in `PID_FOLDER`.
|
||||
Only valid for an `init.d` service
|
||||
|
|
||||
|
|
||||
|
||||
| `useStartStopDaemon`
|
||||
| Whether the `start-stop-daemon` command, when it's available, should be used to control the process
|
||||
| `true`
|
||||
| `true`
|
||||
|
||||
| `stopWaitTime`
|
||||
| Default value for `STOP_WAIT_TIME` in seconds.
|
||||
Only valid for an `init.d` service
|
||||
| 60
|
||||
| 60
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization.when-running]]
|
||||
===== Customizing a Script When It Runs
|
||||
For items of the script that need to be customized _after_ the jar has been written, you can use environment variables or a <<deployment-script-customization-conf-file, config file>>.
|
||||
|
||||
The following environment properties are supported with the default script:
|
||||
|
||||
[cols="1,6"]
|
||||
|===
|
||||
| Variable | Description
|
||||
|
||||
| `MODE`
|
||||
| The "`mode`" of operation.
|
||||
The default depends on the way the jar was built but is usually `auto` (meaning it tries to guess if it is an init script by checking if it is a symlink in a directory called `init.d`).
|
||||
You can explicitly set it to `service` so that the `stop\|start\|status\|restart` commands work or to `run` if you want to run the script in the foreground.
|
||||
|
||||
| `RUN_AS_USER`
|
||||
| The user that will be used to run the application.
|
||||
When not set, the user that owns the jar file will be used.
|
||||
|
||||
| `USE_START_STOP_DAEMON`
|
||||
| Whether the `start-stop-daemon` command, when it's available, should be used to control the process.
|
||||
Defaults to `true`.
|
||||
|
||||
| `PID_FOLDER`
|
||||
| The root name of the pid folder (`/var/run` by default).
|
||||
|
||||
| `LOG_FOLDER`
|
||||
| The name of the folder in which to put log files (`/var/log` by default).
|
||||
|
||||
| `CONF_FOLDER`
|
||||
| The name of the folder from which to read .conf files (same folder as jar-file by default).
|
||||
|
||||
| `LOG_FILENAME`
|
||||
| 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.
|
||||
|
||||
| `RUN_ARGS`
|
||||
| The arguments to pass to the program (the Spring Boot app).
|
||||
|
||||
| `JAVA_HOME`
|
||||
| The location of the `java` executable is discovered by using the `PATH` by default, but you can set it explicitly if there is an executable file at `$JAVA_HOME/bin/java`.
|
||||
|
||||
| `JAVA_OPTS`
|
||||
| Options that are passed to the JVM when it is launched.
|
||||
|
||||
| `JARFILE`
|
||||
| The explicit location of the jar file, in case the script is being used to launch a jar that it is not actually embedded.
|
||||
|
||||
| `DEBUG`
|
||||
| If not empty, sets the `-x` flag on the shell process, allowing you to see the logic in the script.
|
||||
|
||||
| `STOP_WAIT_TIME`
|
||||
| The time in seconds to wait when stopping the application before forcing a shutdown (`60` by default).
|
||||
|===
|
||||
|
||||
NOTE: The `PID_FOLDER`, `LOG_FOLDER`, and `LOG_FILENAME` variables are only valid for an `init.d` service.
|
||||
For `systemd`, the equivalent customizations are made by using the '`service`' script.
|
||||
See the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
|
||||
|
||||
|
||||
|
||||
[[deployment-script-customization-conf-file]]
|
||||
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"]
|
||||
----
|
||||
JAVA_OPTS=-Xmx1024M
|
||||
LOG_FOLDER=/custom/log/folder
|
||||
----
|
||||
|
||||
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.installing.nix-services.init-d.securing,the guidelines for securing an init.d service>>.
|
||||
|
||||
|
||||
|
||||
[[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`].
|
||||
|
||||
A (https://github.com/snicoll/spring-boot-daemon[separately maintained sample]) describes step-by-step how you can create a Windows service for your Spring Boot application.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
Since Spring Boot is so amenable to cloud-based deployment, you can freely consider other providers as well.
|
||||
|
||||
The next section goes on to cover the _<<cli.adoc#cli, Spring Boot CLI>>_, or you can jump ahead to read about _<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_.
|
||||
include::deployment/whats-next.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,415 @@
|
|||
[[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`".
|
||||
They manage application processes (not Java applications 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`, 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.
|
||||
|
||||
In this section, we look at what it takes to get the <<getting-started#getting-started.first-application, application that we developed>> in the "`Getting Started`" section up and running in the Cloud.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
You can deploy stand-alone executable jar applications as well as traditional `.war` packaged applications.
|
||||
|
||||
Once you have built your application (by using, for example, `mvn clean package`) and have https://docs.cloudfoundry.org/cf-cli/install-go-cli.html[installed the `cf` command line tool], deploy your application by using the `cf push` command, substituting the path to your compiled `.jar`.
|
||||
Be sure to have https://docs.cloudfoundry.org/cf-cli/getting-started.html#login[logged in with your `cf` command line client] before pushing an application.
|
||||
The following line shows using the `cf push` command to deploy an application:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ cf push acloudyspringtime -p target/demo-0.0.1-SNAPSHOT.jar
|
||||
----
|
||||
|
||||
NOTE: In the preceding example, we substitute `acloudyspringtime` for whatever value you give `cf` as the name of your application.
|
||||
|
||||
See the https://docs.cloudfoundry.org/cf-cli/getting-started.html#push[`cf push` documentation] for more options.
|
||||
If there is a Cloud Foundry https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html[`manifest.yml`] file present in the same directory, it is considered.
|
||||
|
||||
At this point, `cf` starts uploading your application, producing output similar to the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
Uploading acloudyspringtime... *OK*
|
||||
Preparing to start acloudyspringtime... *OK*
|
||||
-----> Downloaded app package (*8.9M*)
|
||||
-----> Java Buildpack Version: v3.12 (offline) | https://github.com/cloudfoundry/java-buildpack.git#6f25b7e
|
||||
-----> Downloading Open Jdk JRE 1.8.0_121 from https://java-buildpack.cloudfoundry.org/openjdk/trusty/x86_64/openjdk-1.8.0_121.tar.gz (found in cache)
|
||||
Expanding Open Jdk JRE to .java-buildpack/open_jdk_jre (1.6s)
|
||||
-----> Downloading Open JDK Like Memory Calculator 2.0.2_RELEASE from https://java-buildpack.cloudfoundry.org/memory-calculator/trusty/x86_64/memory-calculator-2.0.2_RELEASE.tar.gz (found in cache)
|
||||
Memory Settings: -Xss349K -Xmx681574K -XX:MaxMetaspaceSize=104857K -Xms681574K -XX:MetaspaceSize=104857K
|
||||
-----> Downloading Container Certificate Trust Store 1.0.0_RELEASE from https://java-buildpack.cloudfoundry.org/container-certificate-trust-store/container-certificate-trust-store-1.0.0_RELEASE.jar (found in cache)
|
||||
Adding certificates to .java-buildpack/container_certificate_trust_store/truststore.jks (0.6s)
|
||||
-----> Downloading Spring Auto Reconfiguration 1.10.0_RELEASE from https://java-buildpack.cloudfoundry.org/auto-reconfiguration/auto-reconfiguration-1.10.0_RELEASE.jar (found in cache)
|
||||
Checking status of app 'acloudyspringtime'...
|
||||
0 of 1 instances running (1 starting)
|
||||
...
|
||||
0 of 1 instances running (1 starting)
|
||||
...
|
||||
0 of 1 instances running (1 starting)
|
||||
...
|
||||
1 of 1 instances running (1 running)
|
||||
|
||||
App started
|
||||
----
|
||||
|
||||
Congratulations! The application is now live!
|
||||
|
||||
Once your application is live, you can verify the status of the deployed application by using the `cf apps` command, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ cf apps
|
||||
Getting applications in ...
|
||||
OK
|
||||
|
||||
name requested state instances memory disk urls
|
||||
...
|
||||
acloudyspringtime started 1/1 512M 1G acloudyspringtime.cfapps.io
|
||||
...
|
||||
----
|
||||
|
||||
Once Cloud Foundry acknowledges that your application has been deployed, you should be able to find the application at the URI given.
|
||||
In the preceding example, you could find it at `\https://acloudyspringtime.cfapps.io/`.
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.cloud-foundry.binding-to-services]]
|
||||
==== Binding to Services
|
||||
By default, metadata about the running application as well as service connection information is exposed to the application as environment variables (for example: `$VCAP_SERVICES`).
|
||||
This architecture decision is due to Cloud Foundry's polyglot (any language and platform can be supported as a buildpack) nature.
|
||||
Process-scoped environment variables are language agnostic.
|
||||
|
||||
Environment variables do not always make for the easiest API, so Spring Boot automatically extracts them and flattens the data into properties that can be accessed through Spring's `Environment` abstraction, as shown in the following example:
|
||||
|
||||
[source,java,pending-extract=true,indent=0]
|
||||
----
|
||||
@Component
|
||||
class MyBean implements EnvironmentAware {
|
||||
|
||||
private String instanceId;
|
||||
|
||||
@Override
|
||||
public void setEnvironment(Environment environment) {
|
||||
this.instanceId = environment.getProperty("vcap.application.instance_id");
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
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 the {spring-boot-module-api}/cloud/CloudFoundryVcapEnvironmentPostProcessor.html['`CloudFoundryVcapEnvironmentPostProcessor`'] Javadoc for complete details.
|
||||
|
||||
TIP: The https://github.com/pivotal-cf/java-cfenv/[Java CFEnv] project is a better fit for tasks such as configuring a DataSource.
|
||||
|
||||
|
||||
|
||||
[[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 <<features#features.spring-application.application-availability,manage the state of your application>> and export it with <<actuator#actuator.endpoints.kubernetes-probes, HTTP Kubernetes Probes using Actuator>>.
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.kubernetes.container-lifecycle]]
|
||||
==== Kubernetes Container Lifecycle
|
||||
When Kubernetes deletes an application instance, the shutdown process involves several subsystems concurrently: shutdown hooks, unregistering the service, removing the instance from the load-balancer...
|
||||
Because this shutdown processing happens in parallel (and due to the nature of distributed systems), there is a window during which traffic can be routed to a pod that has also begun its shutdown processing.
|
||||
|
||||
You can configure a sleep execution in a preStop handler to avoid requests being routed to a pod that has already begun shutting down.
|
||||
This sleep should be long enough for new requests to stop being routed to the pod and its duration will vary from deployment to deployment.
|
||||
The preStop handler can be configured via the PodSpec in the pod's configuration file as follows:
|
||||
|
||||
[source,yml,indent=0]
|
||||
----
|
||||
spec:
|
||||
containers:
|
||||
- name: example-container
|
||||
image: example-image
|
||||
lifecycle:
|
||||
preStop:
|
||||
exec:
|
||||
command: ["sh", "-c", "sleep 10"]
|
||||
----
|
||||
|
||||
Once the pre-stop hook has completed, SIGTERM will be sent to the container and <<features#features.graceful-shutdown,graceful shutdown>> will begin, allowing any remaining in-flight requests to complete.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
Heroku assigns a `port` for the Java application to use and then ensures that routing to the external URI works.
|
||||
|
||||
You must configure your application to listen on the correct port.
|
||||
The following example shows the `Procfile` for our starter REST application:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
web: java -Dserver.port=$PORT -jar target/demo-0.0.1-SNAPSHOT.jar
|
||||
----
|
||||
|
||||
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` environment variable is assigned to us by the Heroku PaaS.
|
||||
|
||||
This should be everything you need.
|
||||
The most common deployment workflow for Heroku deployments is to `git push` the code to production, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ git push heroku main
|
||||
|
||||
Initializing repository, *done*.
|
||||
Counting objects: 95, *done*.
|
||||
Delta compression using up to 8 threads.
|
||||
Compressing objects: 100% (78/78), *done*.
|
||||
Writing objects: 100% (95/95), 8.66 MiB | 606.00 KiB/s, *done*.
|
||||
Total 95 (delta 31), reused 0 (delta 0)
|
||||
|
||||
-----> Java app detected
|
||||
-----> Installing OpenJDK 1.8... *done*
|
||||
-----> Installing Maven 3.3.1... *done*
|
||||
-----> Installing settings.xml... *done*
|
||||
-----> Executing: mvn -B -DskipTests=true clean install
|
||||
|
||||
[INFO] Scanning for projects...
|
||||
Downloading: https://repo.spring.io/...
|
||||
Downloaded: https://repo.spring.io/... (818 B at 1.8 KB/sec)
|
||||
....
|
||||
Downloaded: https://s3pository.heroku.com/jvm/... (152 KB at 595.3 KB/sec)
|
||||
[INFO] Installing /tmp/build_0c35a5d2-a067-4abc-a232-14b1fb7a8229/target/...
|
||||
[INFO] Installing /tmp/build_0c35a5d2-a067-4abc-a232-14b1fb7a8229/pom.xml ...
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] *BUILD SUCCESS*
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] Total time: 59.358s
|
||||
[INFO] Finished at: Fri Mar 07 07:28:25 UTC 2014
|
||||
[INFO] Final Memory: 20M/493M
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
|
||||
-----> Discovering process types
|
||||
Procfile declares types -> *web*
|
||||
|
||||
-----> Compressing... *done*, 70.4MB
|
||||
-----> Launching... *done*, v6
|
||||
https://agile-sierra-1405.herokuapp.com/ *deployed to Heroku*
|
||||
|
||||
To git@heroku.com:agile-sierra-1405.git
|
||||
* [new branch] main -> main
|
||||
----
|
||||
|
||||
Your application should now be up and running on Heroku.
|
||||
For more details, refer to https://devcenter.heroku.com/articles/deploying-spring-boot-apps-to-heroku[Deploying Spring Boot Applications to Heroku].
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.openshift]]
|
||||
=== OpenShift
|
||||
https://www.openshift.com/[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]
|
||||
* https://blog.openshift.com/using-spring-boot-on-openshift/[Running as a traditional web application on Wildfly]
|
||||
* https://blog.openshift.com/openshift-commons-briefing-96-cloud-native-applications-spring-rhoar/[OpenShift Commons Briefing]
|
||||
|
||||
|
||||
|
||||
[[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:
|
||||
|
||||
* AWS Elastic Beanstalk
|
||||
* AWS Code Deploy
|
||||
* AWS OPS Works
|
||||
* AWS Cloud Formation
|
||||
* AWS Container Registry
|
||||
|
||||
Each has different features and pricing models.
|
||||
In this document, we describe to approach using AWS Elastic 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`".
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.aws.beanstalk.tomcat-platform]]
|
||||
===== Using the Tomcat Platform
|
||||
This option applies to Spring Boot projects that produce a war file.
|
||||
No special configuration is required.
|
||||
You need only follow the official guide.
|
||||
|
||||
|
||||
|
||||
[[deployment.cloud.aws.beanstalk.java-se-platform]]
|
||||
===== Using the Java SE Platform
|
||||
This option applies to Spring Boot projects that produce a jar file and run an embedded web container.
|
||||
Elastic Beanstalk environments run an nginx instance on port 80 to proxy the actual application, running on port 5000.
|
||||
To configure it, add the following line to your `application.properties` file:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
server.port=5000
|
||||
----
|
||||
|
||||
|
||||
[TIP]
|
||||
.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 lines similar to the following to your `.elasticbeanstalk/config.yml` file:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
deploy:
|
||||
artifact: target/demo-0.0.1-SNAPSHOT.jar
|
||||
----
|
||||
====
|
||||
|
||||
[TIP]
|
||||
.Reduce costs by setting the environment type
|
||||
====
|
||||
By default an Elastic Beanstalk environment is load balanced.
|
||||
The load balancer has a significant cost.
|
||||
To avoid that cost, set the environment type to "`Single instance`", as described in https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html#environments-create-wizard-capacity[the Amazon documentation].
|
||||
You can also create single instance environments by using the CLI and the following command:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
eb create -s
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
Boxfuse leverages this information both for the images it produces as well as for all the resources it provisions (instances, security groups, elastic load balancers, and so on).
|
||||
|
||||
Once you have created a https://console.boxfuse.com[Boxfuse account], connected it to your AWS account, installed the latest version of the Boxfuse Client, and ensured that the application has been built by Maven or Gradle (by using, for example, `mvn clean package`), you can deploy your Spring Boot application to AWS with a command similar to the following:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ boxfuse run myapp-1.0.jar -env=prod
|
||||
----
|
||||
|
||||
See the https://boxfuse.com/docs/commandline/run.html[`boxfuse run` documentation] for more options.
|
||||
If there is a https://boxfuse.com/docs/commandline/#configuration[`boxfuse.conf`] file present in the current directory, it is considered.
|
||||
|
||||
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 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 example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
Fusing Image for myapp-1.0.jar ...
|
||||
Image fused in 00:06.838s (53937 K) -> axelfontaine/myapp:1.0
|
||||
Creating axelfontaine/myapp ...
|
||||
Pushing axelfontaine/myapp:1.0 ...
|
||||
Verifying axelfontaine/myapp:1.0 ...
|
||||
Creating Elastic IP ...
|
||||
Mapping myapp-axelfontaine.boxfuse.io to 52.28.233.167 ...
|
||||
Waiting for AWS to create an AMI for axelfontaine/myapp:1.0 in eu-central-1 (this may take up to 50 seconds) ...
|
||||
AMI created in 00:23.557s -> ami-d23f38cf
|
||||
Creating security group boxfuse-sg_axelfontaine/myapp:1.0 ...
|
||||
Launching t2.micro instance of axelfontaine/myapp:1.0 (ami-d23f38cf) in eu-central-1 ...
|
||||
Instance launched in 00:30.306s -> i-92ef9f53
|
||||
Waiting for AWS to boot Instance i-92ef9f53 and Payload to start at https://52.28.235.61/ ...
|
||||
Payload started in 00:29.266s -> https://52.28.235.61/
|
||||
Remapping Elastic IP 52.28.233.167 to i-92ef9f53 ...
|
||||
Waiting 15s for AWS to complete Elastic IP Zero Downtime transition ...
|
||||
Deployment completed successfully. axelfontaine/myapp:1.0 is up and running at https://myapp-axelfontaine.boxfuse.io/
|
||||
----
|
||||
|
||||
Your application should now be up and running on AWS.
|
||||
|
||||
See the blog post on https://boxfuse.com/blog/spring-boot-ec2.html[deploying Spring Boot apps on EC2] as well as the https://boxfuse.com/docs/payloads/springboot.html[documentation for the Boxfuse Spring Boot integration] to get started with a Maven build to run the app.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
To run in App Engine, you can create a project in the UI first, which sets up a unique identifier for you and also sets up HTTP routes.
|
||||
Add a Java app to the project and leave it empty and then use the https://cloud.google.com/sdk/install[Google Cloud SDK] to push your Spring Boot app into that slot from the command line or CI build.
|
||||
|
||||
App Engine Standard requires you to use WAR packaging.
|
||||
Follow https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/appengine-java8/springboot-helloworld/README.md[these steps] to deploy App Engine Standard application to Google Cloud.
|
||||
|
||||
Alternatively, App Engine Flex requires 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 following file:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
service: default
|
||||
|
||||
runtime: java
|
||||
env: flex
|
||||
|
||||
runtime_config:
|
||||
jdk: openjdk8
|
||||
|
||||
handlers:
|
||||
- url: /.*
|
||||
script: this field is required, but ignored
|
||||
|
||||
manual_scaling:
|
||||
instances: 1
|
||||
|
||||
health_check:
|
||||
enable_health_check: False
|
||||
|
||||
env_variables:
|
||||
ENCRYPT_KEY: your_encryption_key_here
|
||||
----
|
||||
|
||||
You can deploy the app (for example, with a Maven plugin) by adding the project ID to the build configuration, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>com.google.cloud.tools</groupId>
|
||||
<artifactId>appengine-maven-plugin</artifactId>
|
||||
<version>1.3.0</version>
|
||||
<configuration>
|
||||
<project>myproject</project>
|
||||
</configuration>
|
||||
</plugin>
|
||||
----
|
||||
|
||||
Then deploy with `mvn appengine:deploy` (if you need to authenticate first, the build fails).
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
[[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.
|
||||
For example, Cloud Foundry operates this way.
|
||||
One way to run an unpacked archive is by starting the appropriate launcher, as follows:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ jar -xf myapp.jar
|
||||
$ java org.springframework.boot.loader.JarLauncher
|
||||
----
|
||||
|
||||
This is actually slightly faster on startup (depending on the size of the jar) than running from an unexploded archive.
|
||||
At runtime you shouldn't expect any differences.
|
||||
|
||||
Once you have unpacked the jar file, you can also get an extra boost to startup time by running the app with its "natural" main method instead of the `JarLauncher`. For example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ jar -xf myapp.jar
|
||||
$ java -cp BOOT-INF/classes:BOOT-INF/lib/* com.example.MyApplication
|
||||
----
|
||||
|
||||
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 <<features#features.container-images.building.dockerfiles,creating separate layers>> for your dependencies and application classes and resources (which normally change more frequently).
|
||||
|
|
@ -0,0 +1,389 @@
|
|||
[[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#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.
|
||||
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 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.
|
||||
|
||||
CAUTION: A zip64-format jar file cannot be made fully executable.
|
||||
Attempting to do so will result in a jar file that is reported as corrupt when executed directly or with `java -jar`.
|
||||
A standard-format jar file that contains one or more zip64-format nested jars can be fully executable.
|
||||
|
||||
To create a '`fully executable`' jar with Maven, use the following plugin configuration:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<configuration>
|
||||
<executable>true</executable>
|
||||
</configuration>
|
||||
</plugin>
|
||||
----
|
||||
|
||||
The following example shows the equivalent Gradle configuration:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
bootJar {
|
||||
launchScript()
|
||||
}
|
||||
----
|
||||
|
||||
You can then run your application by typing `./my-application.jar` (where `my-application` is the name of your artifact).
|
||||
The directory containing the jar is used as your application's working directory.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.supported-operating-systems]]
|
||||
=== Supported Operating Systems
|
||||
The default script supports most Linux distributions and is tested on CentOS and Ubuntu.
|
||||
Other platforms, such as OS X and FreeBSD, require the use of a custom `embeddedLaunchScript`.
|
||||
|
||||
|
||||
|
||||
[[deployment.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.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#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:
|
||||
|
||||
* Starts the services as the user that owns the jar file
|
||||
* Tracks the application's PID by using `/var/run/<appname>/<appname>.pid`
|
||||
* Writes console logs to `/var/log/<appname>.log`
|
||||
|
||||
Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a Spring Boot application as an `init.d` service, create a symlink, as follows:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ sudo ln -s /var/myapp/myapp.jar /etc/init.d/myapp
|
||||
----
|
||||
|
||||
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:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ service myapp start
|
||||
----
|
||||
|
||||
TIP: If your application fails to start, check the log file written to `/var/log/<appname>.log` for errors.
|
||||
|
||||
You can also flag the application to start automatically by using your standard operating system tools.
|
||||
For example, on Debian, you could use the following command:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ update-rc.d myapp defaults <priority>
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.init-d.securing]]
|
||||
===== Securing an init.d Service
|
||||
NOTE: The following is a set of guidelines on how to secure a Spring Boot application that runs as an init.d service.
|
||||
It is not intended to be an exhaustive list of everything that should be done to harden an application and the environment in which it runs.
|
||||
|
||||
When executed as root, as is the case when root is being used to start an init.d service, the default executable script runs the application as the user specified in the `RUN_AS_USER` environment variable.
|
||||
When the environment variable is not set, the user who owns the jar file is used instead.
|
||||
You should never run a Spring Boot application as `root`, so `RUN_AS_USER` should never be root and your application's jar file should never be owned by root.
|
||||
Instead, create a specific user to run your application and set the `RUN_AS_USER` environment variable or use `chown` to make it the owner of the jar file, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ chown bootapp:bootapp your-app.jar
|
||||
----
|
||||
|
||||
In this case, the default executable script runs the application as the `bootapp` user.
|
||||
|
||||
TIP: To reduce the chances of the application's user account being compromised, you should consider preventing it from using a login shell.
|
||||
For example, you can set the account's shell to `/usr/sbin/nologin`.
|
||||
|
||||
You should also take steps to prevent the modification of your application's jar file.
|
||||
Firstly, configure its permissions so that it cannot be written and can only be read or executed by its owner, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ chmod 500 your-app.jar
|
||||
----
|
||||
|
||||
Second, you should also take steps to limit the damage if your application or the account that's running it is compromised.
|
||||
If an attacker does gain access, they could make the jar file writable and change its contents.
|
||||
One way to protect against this is to make it immutable by using `chattr`, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ sudo chattr +i your-app.jar
|
||||
----
|
||||
|
||||
This will prevent any user, including root, from modifying the jar.
|
||||
|
||||
If root is used to control the application's service and you <<deployment#deployment.installing.nix-services.script-customization.when-running.conf-file, use a `.conf` file>> to customize its startup, the `.conf` file is read and evaluated by the root user.
|
||||
It should be secured accordingly.
|
||||
Use `chmod` so that the file can only be read by the owner and use `chown` to make root the owner, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ chmod 400 your-app.conf
|
||||
$ sudo chown root:root your-app.conf
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a Spring Boot application as a `systemd` service, create a script named `myapp.service` and place it in `/etc/systemd/system` directory.
|
||||
The following script offers an example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
[Unit]
|
||||
Description=myapp
|
||||
After=syslog.target
|
||||
|
||||
[Service]
|
||||
User=myapp
|
||||
ExecStart=/var/myapp/myapp.jar
|
||||
SuccessExitStatus=143
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
----
|
||||
|
||||
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 the `run` command is used by default.
|
||||
|
||||
Note that, unlike when running as an `init.d` service, the user that runs the application, the PID file, and the console log file are managed by `systemd` itself and therefore must be configured by using appropriate fields in the '`service`' script.
|
||||
Consult the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
|
||||
|
||||
To flag the application to start automatically on system boot, use the following command:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ systemctl enable myapp.service
|
||||
----
|
||||
|
||||
Refer to `man systemctl` for more details.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization]]
|
||||
==== Customizing the Startup Script
|
||||
The default embedded startup script written by the Maven or Gradle plugin can be customized in a number of ways.
|
||||
For most people, using the default script along with a few customizations is usually enough.
|
||||
If you find you cannot customize something that you need to, use the `embeddedLaunchScript` option to write your own file entirely.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization.when-written]]
|
||||
===== Customizing the Start Script When It Is Written
|
||||
It often makes sense to customize elements of the start script as it is written into the jar file.
|
||||
For example, init.d scripts can provide a "`description`".
|
||||
Since you know the description up front (and it need not change), you may as well provide it when the jar is generated.
|
||||
|
||||
To customize written elements, use the `embeddedLaunchScriptProperties` option of the Spring Boot Maven plugin or the {spring-boot-gradle-plugin-docs}#packaging-executable-configuring-launch-script[`properties` property of the Spring Boot Gradle plugin's `launchScript`].
|
||||
|
||||
The following property substitutions are supported with the default script:
|
||||
|
||||
[cols="1,3,3,3"]
|
||||
|===
|
||||
| Name | Description | Gradle default | Maven default
|
||||
|
||||
| `mode`
|
||||
| The script mode.
|
||||
| `auto`
|
||||
| `auto`
|
||||
|
||||
| `initInfoProvides`
|
||||
| The `Provides` section of "`INIT INFO`"
|
||||
| `${task.baseName}`
|
||||
| `${project.artifactId}`
|
||||
|
||||
| `initInfoRequiredStart`
|
||||
| `Required-Start` section of "`INIT INFO`".
|
||||
| `$remote_fs $syslog $network`
|
||||
| `$remote_fs $syslog $network`
|
||||
|
||||
| `initInfoRequiredStop`
|
||||
| `Required-Stop` section of "`INIT INFO`".
|
||||
| `$remote_fs $syslog $network`
|
||||
| `$remote_fs $syslog $network`
|
||||
|
||||
| `initInfoDefaultStart`
|
||||
| `Default-Start` section of "`INIT INFO`".
|
||||
| `2 3 4 5`
|
||||
| `2 3 4 5`
|
||||
|
||||
| `initInfoDefaultStop`
|
||||
| `Default-Stop` section of "`INIT INFO`".
|
||||
| `0 1 6`
|
||||
| `0 1 6`
|
||||
|
||||
| `initInfoShortDescription`
|
||||
| `Short-Description` section of "`INIT INFO`".
|
||||
| Single-line version of `${project.description}` (falling back to `${task.baseName}`)
|
||||
| `${project.name}`
|
||||
|
||||
| `initInfoDescription`
|
||||
| `Description` section of "`INIT INFO`".
|
||||
| `${project.description}` (falling back to `${task.baseName}`)
|
||||
| `${project.description}` (falling back to `${project.name}`)
|
||||
|
||||
| `initInfoChkconfig`
|
||||
| `chkconfig` section of "`INIT INFO`"
|
||||
| `2345 99 01`
|
||||
| `2345 99 01`
|
||||
|
||||
| `confFolder`
|
||||
| The default value for `CONF_FOLDER`
|
||||
| Folder containing the jar
|
||||
| Folder containing the jar
|
||||
|
||||
| `inlinedConfScript`
|
||||
| Reference to a file script that should be inlined in the default launch script.
|
||||
This can be used to set environmental variables such as `JAVA_OPTS` before any external config files are loaded
|
||||
|
|
||||
|
|
||||
|
||||
| `logFolder`
|
||||
| Default value for `LOG_FOLDER`.
|
||||
Only valid for an `init.d` service
|
||||
|
|
||||
|
|
||||
|
||||
| `logFilename`
|
||||
| Default value for `LOG_FILENAME`.
|
||||
Only valid for an `init.d` service
|
||||
|
|
||||
|
|
||||
|
||||
| `pidFolder`
|
||||
| Default value for `PID_FOLDER`.
|
||||
Only valid for an `init.d` service
|
||||
|
|
||||
|
|
||||
|
||||
| `pidFilename`
|
||||
| Default value for the name of the PID file in `PID_FOLDER`.
|
||||
Only valid for an `init.d` service
|
||||
|
|
||||
|
|
||||
|
||||
| `useStartStopDaemon`
|
||||
| Whether the `start-stop-daemon` command, when it's available, should be used to control the process
|
||||
| `true`
|
||||
| `true`
|
||||
|
||||
| `stopWaitTime`
|
||||
| Default value for `STOP_WAIT_TIME` in seconds.
|
||||
Only valid for an `init.d` service
|
||||
| 60
|
||||
| 60
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization.when-running]]
|
||||
===== Customizing a Script When It Runs
|
||||
For items of the script that need to be customized _after_ the jar has been written, you can use environment variables or a <<deployment#deployment.installing.nix-services.script-customization.when-running.conf-file, config file>>.
|
||||
|
||||
The following environment properties are supported with the default script:
|
||||
|
||||
[cols="1,6"]
|
||||
|===
|
||||
| Variable | Description
|
||||
|
||||
| `MODE`
|
||||
| The "`mode`" of operation.
|
||||
The default depends on the way the jar was built but is usually `auto` (meaning it tries to guess if it is an init script by checking if it is a symlink in a directory called `init.d`).
|
||||
You can explicitly set it to `service` so that the `stop\|start\|status\|restart` commands work or to `run` if you want to run the script in the foreground.
|
||||
|
||||
| `RUN_AS_USER`
|
||||
| The user that will be used to run the application.
|
||||
When not set, the user that owns the jar file will be used.
|
||||
|
||||
| `USE_START_STOP_DAEMON`
|
||||
| Whether the `start-stop-daemon` command, when it's available, should be used to control the process.
|
||||
Defaults to `true`.
|
||||
|
||||
| `PID_FOLDER`
|
||||
| The root name of the pid folder (`/var/run` by default).
|
||||
|
||||
| `LOG_FOLDER`
|
||||
| The name of the folder in which to put log files (`/var/log` by default).
|
||||
|
||||
| `CONF_FOLDER`
|
||||
| The name of the folder from which to read .conf files (same folder as jar-file by default).
|
||||
|
||||
| `LOG_FILENAME`
|
||||
| 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.
|
||||
|
||||
| `RUN_ARGS`
|
||||
| The arguments to pass to the program (the Spring Boot app).
|
||||
|
||||
| `JAVA_HOME`
|
||||
| The location of the `java` executable is discovered by using the `PATH` by default, but you can set it explicitly if there is an executable file at `$JAVA_HOME/bin/java`.
|
||||
|
||||
| `JAVA_OPTS`
|
||||
| Options that are passed to the JVM when it is launched.
|
||||
|
||||
| `JARFILE`
|
||||
| The explicit location of the jar file, in case the script is being used to launch a jar that it is not actually embedded.
|
||||
|
||||
| `DEBUG`
|
||||
| If not empty, sets the `-x` flag on the shell process, allowing you to see the logic in the script.
|
||||
|
||||
| `STOP_WAIT_TIME`
|
||||
| The time in seconds to wait when stopping the application before forcing a shutdown (`60` by default).
|
||||
|===
|
||||
|
||||
NOTE: The `PID_FOLDER`, `LOG_FOLDER`, and `LOG_FILENAME` variables are only valid for an `init.d` service.
|
||||
For `systemd`, the equivalent customizations are made by using the '`service`' script.
|
||||
See the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization.when-running.conf-file]]
|
||||
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"]
|
||||
----
|
||||
JAVA_OPTS=-Xmx1024M
|
||||
LOG_FOLDER=/custom/log/folder
|
||||
----
|
||||
|
||||
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#deployment.installing.nix-services.init-d.securing,the guidelines for securing an init.d service>>.
|
||||
|
||||
|
||||
|
||||
[[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`].
|
||||
|
||||
A (https://github.com/snicoll/spring-boot-daemon[separately maintained sample]) describes step-by-step how you can create a Windows service for your Spring Boot application.
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
[[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.
|
||||
Since Spring Boot is so amenable to cloud-based deployment, you can freely consider other providers as well.
|
||||
|
||||
The next section goes on to cover the _<<cli#cli, Spring Boot CLI>>_, or you can jump ahead to read about _<<build-tool-plugins#build-tool-plugins, build tool plugins>>_.
|
||||
|
|
@ -1,107 +1,30 @@
|
|||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
[[documentation]]
|
||||
= Spring Boot Documentation
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
This section provides a brief overview of Spring Boot reference documentation.
|
||||
It serves as a map for the rest of the document.
|
||||
|
||||
|
||||
|
||||
[[documentation.about]]
|
||||
== About the Documentation
|
||||
The Spring Boot reference guide is available as:
|
||||
include::documentation/about.adoc[]
|
||||
|
||||
* {spring-boot-docs}/html/[Multi-page HTML]
|
||||
* {spring-boot-docs}/htmlsingle/[Single page HTML]
|
||||
* {spring-boot-docs}/pdf/spring-boot-reference.pdf[PDF]
|
||||
include::documentation/getting-help.adoc[]
|
||||
|
||||
The latest copy is available at {spring-boot-current-docs}.
|
||||
include::documentation/upgrading.adoc[]
|
||||
|
||||
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
|
||||
include::documentation/first-steps.adoc[]
|
||||
|
||||
include::documentation/using.adoc[]
|
||||
|
||||
include::documentation/features.adoc[]
|
||||
|
||||
[[documentation.getting-help]]
|
||||
== Getting Help
|
||||
If you have trouble with Spring Boot, we would like to help.
|
||||
include::documentation/actuator.adoc[]
|
||||
|
||||
* Try the <<howto.adoc#howto, How-to documents>>.
|
||||
They provide solutions to the most common questions.
|
||||
* Learn the Spring basics.
|
||||
Spring Boot builds on many other Spring projects.
|
||||
Check the https://spring.io[spring.io] web-site for a wealth of reference documentation.
|
||||
If you are starting out with Spring, try one of the https://spring.io/guides[guides].
|
||||
* Ask a question.
|
||||
We monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-boot[`spring-boot`].
|
||||
* Report bugs with Spring Boot at https://github.com/spring-projects/spring-boot/issues.
|
||||
|
||||
NOTE: All of Spring Boot is open source, including the documentation.
|
||||
If you find problems with the docs or if you want to improve them, please {spring-boot-code}[get involved].
|
||||
|
||||
|
||||
|
||||
[[documentation.upgrading]]
|
||||
== Upgrading From an Earlier Version
|
||||
Instructions for how to upgrade from earlier versions of Spring Boot are provided on the project {github-wiki}[wiki].
|
||||
Follow the links in the {github-wiki}#release-notes[release notes] section to find the version that you want to upgrade to.
|
||||
|
||||
Upgrading instructions are always the first item in the release notes.
|
||||
If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped.
|
||||
|
||||
You should always ensure that you are running a {github-wiki}/Supported-Versions[supported version] of Spring Boot.
|
||||
|
||||
|
||||
|
||||
[[documentation.first-steps]]
|
||||
== First Steps
|
||||
If you are getting started with Spring Boot or 'Spring' in general, start with <<getting-started.adoc#getting-started, the following topics>>:
|
||||
|
||||
* *From scratch:* <<getting-started.adoc#getting-started.introducing-spring-boot, Overview>> | <<getting-started.adoc#getting-started.system-requirements, Requirements>> | <<getting-started.adoc#getting-started.installing, Installation>>
|
||||
* *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>>
|
||||
|
||||
|
||||
|
||||
[[documentation.using]]
|
||||
== Working with Spring Boot
|
||||
Ready to actually start using Spring Boot? <<using.adoc#using, We have you covered>>:
|
||||
|
||||
* *Build systems:* <<using.adoc#using.build-systems.maven, Maven>> | <<using.adoc#using.build-systems.gradle, Gradle>> | <<using.adoc#using.build-systems.ant, Ant>> | <<using.adoc#using.build-systems.starters, Starters>>
|
||||
* *Best practices:* <<using.adoc#using.structuring-your-code, Code Structure>> | <<using.adoc#using.configuration-classes, @Configuration>> | <<using.adoc#using.auto-configuration, @EnableAutoConfiguration>> | <<using.adoc#using.spring-beans-and-dependency-injection, Beans and Dependency Injection>>
|
||||
* *Running your code:* <<using.adoc#using.running-your-application.from-an-ide, IDE>> | <<using.adoc#using.running-your-application.as-a-packaged-application, Packaged>> | <<using.adoc#using.running-your-application.with-the-maven-plugin, Maven>> | <<using.adoc#using.running-your-application.with-the-gradle-plugin, Gradle>>
|
||||
* *Packaging your app:* <<using.adoc#using.packaging-for-production, Production jars>>
|
||||
* *Spring Boot CLI:* <<cli.adoc#cli, Using the CLI>>
|
||||
|
||||
|
||||
|
||||
[[documentation.features]]
|
||||
== Learning About Spring Boot Features
|
||||
Need more details about Spring Boot's core features?
|
||||
<<features.adoc#features, The following content is for you>>:
|
||||
|
||||
* *Core Features:* <<features.adoc#features.spring-application, SpringApplication>> | <<features.adoc#features.external-config, External Configuration>> | <<features.adoc#features.profiles, Profiles>> | <<features.adoc#features.logging, Logging>>
|
||||
* *Web Applications:* <<features.adoc#features.developing-web-applications.spring-mvc, MVC>> | <<features.adoc#features.developing-web-applications.embedded-container, Embedded Containers>>
|
||||
* *Working with data:* <<features.adoc#features.sql, SQL>> | <<features.adoc#features.nosql, NO-SQL>>
|
||||
* *Messaging:* <<features.adoc#features.messaging, Overview>> | <<features.adoc#features.messaging.jms, JMS>>
|
||||
* *Testing:* <<features.adoc#features.testing, Overview>> | <<features.adoc#features.testing.spring-boot-applications, Boot Applications>> | <<features.adoc#features.testing.utilities, Utils>>
|
||||
* *Extending:* <<features.adoc#features.developing-auto-configuration, Auto-configuration>> | <<features.adoc#features.developing-auto-configuration.condition-annotations, @Conditions>>
|
||||
|
||||
|
||||
|
||||
[[documentation.actuator]]
|
||||
== Moving to Production
|
||||
When you are ready to push your Spring Boot application to production, we have <<actuator.adoc#actuator, some tricks>> that you might like:
|
||||
|
||||
* *Management endpoints:* <<actuator.adoc#actuator.endpoints, Overview>>
|
||||
* *Connection options:* <<actuator.adoc#actuator.monitoring, HTTP>> | <<actuator.adoc#actuator.jmx, JMX>>
|
||||
* *Monitoring:* <<actuator.adoc#actuator.metrics, Metrics>> | <<actuator.adoc#actuator.auditing, Auditing>> | <<actuator.adoc#actuator.tracing, HTTP Tracing>> | <<actuator.adoc#actuator.process-monitoring, Process>>
|
||||
|
||||
|
||||
|
||||
[[documentation.advanced]]
|
||||
== Advanced Topics
|
||||
Finally, we have a few topics for more advanced users:
|
||||
|
||||
* *Spring Boot Applications Deployment:* <<deployment.adoc#deployment.cloud, Cloud Deployment>> | <<deployment.adoc#deployment.installing.nix-services, OS Service>>
|
||||
* *Build tool plugins:* <<build-tool-plugins.adoc#build-tool-plugins.maven, Maven>> | <<build-tool-plugins.adoc#build-tool-plugins.gradle, Gradle>>
|
||||
* *Appendix:* <<common-application-properties.adoc#appendix.common-application-properties,Application Properties>> | <<configuration-metadata.adoc#appendix.configuration-metadata,Configuration Metadata>> | <<auto-configuration-classes.adoc#appendix.auto-configuration-classes,Auto-configuration Classes>> | <<test-auto-configuration.adoc#appendix.test-auto-configuration,Test Auto-configuration Annotations>> | <<executable-jar.adoc#appendix.executable-jar,Executable Jars>> | <<dependency-versions.adoc#appendix.dependency-versions,Dependency Versions>>
|
||||
include::documentation/advanced.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,11 @@
|
|||
[[documentation.about]]
|
||||
== About the Documentation
|
||||
The Spring Boot reference guide is available as:
|
||||
|
||||
* {spring-boot-docs}/html/[Multi-page HTML]
|
||||
* {spring-boot-docs}/htmlsingle/[Single page HTML]
|
||||
* {spring-boot-docs}/pdf/spring-boot-reference.pdf[PDF]
|
||||
|
||||
The latest copy is available at {spring-boot-current-docs}.
|
||||
|
||||
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
[[documentation.actuator]]
|
||||
== Moving to Production
|
||||
When you are ready to push your Spring Boot application to production, we have <<actuator#actuator, some tricks>> that you might like:
|
||||
|
||||
* *Management endpoints:* <<actuator#actuator.endpoints, Overview>>
|
||||
* *Connection options:* <<actuator#actuator.monitoring, HTTP>> | <<actuator#actuator.jmx, JMX>>
|
||||
* *Monitoring:* <<actuator#actuator.metrics, Metrics>> | <<actuator#actuator.auditing, Auditing>> | <<actuator#actuator.tracing, HTTP Tracing>> | <<actuator#actuator.process-monitoring, Process>>
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
[[documentation.advanced]]
|
||||
== Advanced Topics
|
||||
Finally, we have a few topics for more advanced users:
|
||||
|
||||
* *Spring Boot Applications Deployment:* <<deployment#deployment.cloud, Cloud Deployment>> | <<deployment#deployment.installing.nix-services, OS Service>>
|
||||
* *Build tool plugins:* <<build-tool-plugins#build-tool-plugins.maven, Maven>> | <<build-tool-plugins#build-tool-plugins.gradle, Gradle>>
|
||||
* *Appendix:* <<application-properties#application-properties,Application Properties>> | <<configuration-metadata#configuration-metadata,Configuration Metadata>> | <<auto-configuration-classes#auto-configuration-classes,Auto-configuration Classes>> | <<test-auto-configuration#test-auto-configuration,Test Auto-configuration Annotations>> | <<executable-jar#executable-jar,Executable Jars>> | <<dependency-versions#dependency-versions,Dependency Versions>>
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
[[documentation.features]]
|
||||
== Learning About Spring Boot Features
|
||||
Need more details about Spring Boot's core features?
|
||||
<<features#features, The following content is for you>>:
|
||||
|
||||
* *Core Features:* <<features#features.spring-application, SpringApplication>> | <<features#features.external-config, External Configuration>> | <<features#features.profiles, Profiles>> | <<features#features.logging, Logging>>
|
||||
* *Web Applications:* <<features#features.developing-web-applications.spring-mvc, MVC>> | <<features#features.developing-web-applications.embedded-container, Embedded Containers>>
|
||||
* *Working with data:* <<features#features.sql, SQL>> | <<features#features.nosql, NO-SQL>>
|
||||
* *Messaging:* <<features#features.messaging, Overview>> | <<features#features.messaging.jms, JMS>>
|
||||
* *Testing:* <<features#features.testing, Overview>> | <<features#features.testing.spring-boot-applications, Boot Applications>> | <<features#features.testing.utilities, Utils>>
|
||||
* *Extending:* <<features#features.developing-auto-configuration, Auto-configuration>> | <<features#features.developing-auto-configuration.condition-annotations, @Conditions>>
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
[[documentation.first-steps]]
|
||||
== First Steps
|
||||
If you are getting started with Spring Boot or 'Spring' in general, start with <<getting-started#getting-started, the following topics>>:
|
||||
|
||||
* *From scratch:* <<getting-started#getting-started.introducing-spring-boot, Overview>> | <<getting-started#getting-started.system-requirements, Requirements>> | <<getting-started#getting-started.installing, Installation>>
|
||||
* *Tutorial:* <<getting-started#getting-started.first-application, Part 1>> | <<getting-started#getting-started.first-application.code, Part 2>>
|
||||
* *Running your example:* <<getting-started#getting-started.first-application.run, Part 1>> | <<getting-started#getting-started.first-application.executable-jar, Part 2>>
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
[[documentation.getting-help]]
|
||||
== Getting Help
|
||||
If you have trouble with Spring Boot, we would like to help.
|
||||
|
||||
* Try the <<howto#howto, How-to documents>>.
|
||||
They provide solutions to the most common questions.
|
||||
* Learn the Spring basics.
|
||||
Spring Boot builds on many other Spring projects.
|
||||
Check the https://spring.io[spring.io] web-site for a wealth of reference documentation.
|
||||
If you are starting out with Spring, try one of the https://spring.io/guides[guides].
|
||||
* Ask a question.
|
||||
We monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-boot[`spring-boot`].
|
||||
* Report bugs with Spring Boot at https://github.com/spring-projects/spring-boot/issues.
|
||||
|
||||
NOTE: All of Spring Boot is open source, including the documentation.
|
||||
If you find problems with the docs or if you want to improve them, please {spring-boot-code}[get involved].
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
[[documentation.upgrading]]
|
||||
== Upgrading From an Earlier Version
|
||||
Instructions for how to upgrade from earlier versions of Spring Boot are provided on the project {github-wiki}[wiki].
|
||||
Follow the links in the {github-wiki}#release-notes[release notes] section to find the version that you want to upgrade to.
|
||||
|
||||
Upgrading instructions are always the first item in the release notes.
|
||||
If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped.
|
||||
|
||||
You should always ensure that you are running a {github-wiki}/Supported-Versions[supported version] of Spring Boot.
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
[[documentation.using]]
|
||||
== Working with Spring Boot
|
||||
Ready to actually start using Spring Boot? <<using#using, We have you covered>>:
|
||||
|
||||
* *Build systems:* <<using#using.build-systems.maven, Maven>> | <<using#using.build-systems.gradle, Gradle>> | <<using#using.build-systems.ant, Ant>> | <<using#using.build-systems.starters, Starters>>
|
||||
* *Best practices:* <<using#using.structuring-your-code, Code Structure>> | <<using#using.configuration-classes, @Configuration>> | <<using#using.auto-configuration, @EnableAutoConfiguration>> | <<using#using.spring-beans-and-dependency-injection, Beans and Dependency Injection>>
|
||||
* *Running your code:* <<using#using.running-your-application.from-an-ide, IDE>> | <<using#using.running-your-application.as-a-packaged-application, Packaged>> | <<using#using.running-your-application.with-the-maven-plugin, Maven>> | <<using#using.running-your-application.with-the-gradle-plugin, Gradle>>
|
||||
* *Packaging your app:* <<using#using.packaging-for-production, Production jars>>
|
||||
* *Spring Boot CLI:* <<cli#cli, Using the CLI>>
|
||||
|
|
@ -1,8 +1,10 @@
|
|||
[appendix]
|
||||
[[appendix.executable-jar]]
|
||||
[[executable-jar]]
|
||||
= The Executable Jar Format
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
|
||||
The `spring-boot-loader` modules lets Spring Boot support executable jar and war files.
|
||||
If you use the Maven plugin or the Gradle plugin, executable jars are automatically generated, and you generally do not need to know the details of how they work.
|
||||
|
||||
|
|
@ -10,339 +12,14 @@ If you need to create executable jars from a different build system or if you ar
|
|||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
include::executable-jar/nested-jars.adoc[]
|
||||
|
||||
To solve this problem, many developers use "`shaded`" jars.
|
||||
A shaded jar packages all classes, from all jars, into a single "`uber jar`".
|
||||
The problem with shaded jars is that it becomes hard to see which libraries are actually in your application.
|
||||
It can also be problematic if the same filename is used (but with different content) in multiple jars.
|
||||
Spring Boot takes a different approach and lets you actually nest jars directly.
|
||||
include::executable-jar/jarfile-class.adoc[]
|
||||
|
||||
include::executable-jar/launching.adoc[]
|
||||
|
||||
include::executable-jar/property-launcher.adoc[]
|
||||
|
||||
[[appendix.executable-jar.nested-jars.jar-structure]]
|
||||
=== The Executable Jar File Structure
|
||||
Spring Boot Loader-compatible jar files should be structured in the following way:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
example.jar
|
||||
|
|
||||
+-META-INF
|
||||
| +-MANIFEST.MF
|
||||
+-org
|
||||
| +-springframework
|
||||
| +-boot
|
||||
| +-loader
|
||||
| +-<spring boot loader classes>
|
||||
+-BOOT-INF
|
||||
+-classes
|
||||
| +-mycompany
|
||||
| +-project
|
||||
| +-YourClasses.class
|
||||
+-lib
|
||||
+-dependency1.jar
|
||||
+-dependency2.jar
|
||||
----
|
||||
|
||||
Application classes should be placed in a nested `BOOT-INF/classes` directory.
|
||||
Dependencies should be placed in a nested `BOOT-INF/lib` directory.
|
||||
|
||||
|
||||
|
||||
[[appendix.executable-jar.nested-jars.war-structure]]
|
||||
=== The Executable War File Structure
|
||||
Spring Boot Loader-compatible war files should be structured in the following way:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
example.war
|
||||
|
|
||||
+-META-INF
|
||||
| +-MANIFEST.MF
|
||||
+-org
|
||||
| +-springframework
|
||||
| +-boot
|
||||
| +-loader
|
||||
| +-<spring boot loader classes>
|
||||
+-WEB-INF
|
||||
+-classes
|
||||
| +-com
|
||||
| +-mycompany
|
||||
| +-project
|
||||
| +-YourClasses.class
|
||||
+-lib
|
||||
| +-dependency1.jar
|
||||
| +-dependency2.jar
|
||||
+-lib-provided
|
||||
+-servlet-api.jar
|
||||
+-dependency3.jar
|
||||
----
|
||||
|
||||
Dependencies should be placed in a nested `WEB-INF/lib` directory.
|
||||
Any dependencies that are required when running embedded but are not required when deploying to a traditional web container should be placed in `WEB-INF/lib-provided`.
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
The `layers.idx` file can be used only for jars, and it allows a jar to be split into logical layers for Docker/OCI image creation.
|
||||
|
||||
Index files follow a YAML compatible syntax so that they can be easily parsed by third-party tools.
|
||||
These files, however, are _not_ parsed internally as YAML and they must be written in exactly the formats described below in order to be used.
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
Each line must start with dash space (`"-·"`) and names must be in double quotes.
|
||||
|
||||
For example, given the following jar:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
example.jar
|
||||
|
|
||||
+-META-INF
|
||||
| +-...
|
||||
+-BOOT-INF
|
||||
+-classes
|
||||
| +...
|
||||
+-lib
|
||||
+-dependency1.jar
|
||||
+-dependency2.jar
|
||||
----
|
||||
|
||||
The index file would look like this:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
- "BOOT-INF/lib/dependency2.jar"
|
||||
- "BOOT-INF/lib/dependency1.jar"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
Layers are written in the order that they should be added to the Docker/OCI image.
|
||||
Layers names are written as quoted strings prefixed with dash space (`"-·"`) and with a colon (`":"`) suffix.
|
||||
Layer content is either a file or directory name written as a quoted string prefixed by space space dash space (`"··-·"`).
|
||||
A directory name ends with `/`, a file name does not.
|
||||
When a directory name is used it means that all files inside that directory are in the same layer.
|
||||
|
||||
A typical example of a layers index would be:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
- "dependencies":
|
||||
- "BOOT-INF/lib/dependency1.jar"
|
||||
- "BOOT-INF/lib/dependency2.jar"
|
||||
- "application":
|
||||
- "BOOT-INF/classes/"
|
||||
- "META-INF/"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
When first loaded, the location of each `JarEntry` is mapped to a physical file offset of the outer jar, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
myapp.jar
|
||||
+-------------------+-------------------------+
|
||||
| /BOOT-INF/classes | /BOOT-INF/lib/mylib.jar |
|
||||
|+-----------------+||+-----------+----------+|
|
||||
|| A.class ||| B.class | C.class ||
|
||||
|+-----------------+||+-----------+----------+|
|
||||
+-------------------+-------------------------+
|
||||
^ ^ ^
|
||||
0063 3452 3980
|
||||
----
|
||||
|
||||
The preceding example shows how `A.class` can be found in `/BOOT-INF/classes` in `myapp.jar` at position `0063`.
|
||||
`B.class` from the nested jar can actually be found in `myapp.jar` at position `3452`, and `C.class` is at position `3980`.
|
||||
|
||||
Armed with this information, we can load specific nested entries by seeking to the appropriate part of the outer jar.
|
||||
We do not need to unpack the archive, and we do not need to read all entry data into memory.
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
The `getURL()` method returns a `URL` that opens a connection compatible with `java.net.JarURLConnection` and can be used with Java's `URLClassLoader`.
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
|
||||
There are three launcher subclasses (`JarLauncher`, `WarLauncher`, and `PropertiesLauncher`).
|
||||
Their purpose is to load resources (`.class` files and so on) from nested jar files or war files in directories (as opposed to those explicitly on the classpath).
|
||||
In the case of `JarLauncher` and `WarLauncher`, the nested paths are fixed.
|
||||
`JarLauncher` looks in `BOOT-INF/lib/`, and `WarLauncher` looks in `WEB-INF/lib/` and `WEB-INF/lib-provided/`.
|
||||
You can add extra jars in those locations if you want more.
|
||||
The `PropertiesLauncher` looks in `BOOT-INF/lib/` in your application archive by default.
|
||||
You can add additional locations by setting an environment variable called `LOADER_PATH` or `loader.path` in `loader.properties` (which is a comma-separated list of directories, archives, or directories within archives).
|
||||
|
||||
|
||||
|
||||
[[appendix.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.
|
||||
|
||||
The following example shows a typical `MANIFEST.MF` for an executable jar file:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
Main-Class: org.springframework.boot.loader.JarLauncher
|
||||
Start-Class: com.mycompany.project.MyApplication
|
||||
----
|
||||
|
||||
For a war file, it would be as follows:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
Main-Class: org.springframework.boot.loader.WarLauncher
|
||||
Start-Class: com.mycompany.project.MyApplication
|
||||
----
|
||||
|
||||
NOTE: You need not specify `Class-Path` entries in your manifest file.
|
||||
The classpath is deduced from the nested jars.
|
||||
|
||||
|
||||
|
||||
[[appendix.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:
|
||||
|
||||
|===
|
||||
| Key | Purpose
|
||||
|
||||
| `loader.path`
|
||||
| Comma-separated Classpath, such as `lib,$\{HOME}/app/lib`.
|
||||
Earlier entries take precedence, like a regular `-classpath` on the `javac` command line.
|
||||
|
||||
| `loader.home`
|
||||
| Used to resolve relative paths in `loader.path`.
|
||||
For example, given `loader.path=lib`, then `${loader.home}/lib` is a classpath location (along with all jar files in that directory).
|
||||
This property is also used to locate a `loader.properties` file, as in the following example `file:///opt/app` It defaults to `${user.dir}`.
|
||||
|
||||
| `loader.args`
|
||||
| Default arguments for the main method (space separated).
|
||||
|
||||
| `loader.main`
|
||||
| Name of main class to launch (for example, `com.app.Application`).
|
||||
|
||||
| `loader.config.name`
|
||||
| Name of properties file (for example, `launcher`).
|
||||
It defaults to `loader`.
|
||||
|
||||
| `loader.config.location`
|
||||
| Path to properties file (for example, `classpath:loader.properties`).
|
||||
It defaults to `loader.properties`.
|
||||
|
||||
| `loader.system`
|
||||
| Boolean flag to indicate that all properties should be added to System properties.
|
||||
It defaults to `false`.
|
||||
|===
|
||||
|
||||
When specified as environment variables or manifest entries, the following names should be used:
|
||||
|
||||
|===
|
||||
| Key | Manifest entry | Environment variable
|
||||
|
||||
| `loader.path`
|
||||
| `Loader-Path`
|
||||
| `LOADER_PATH`
|
||||
|
||||
| `loader.home`
|
||||
| `Loader-Home`
|
||||
| `LOADER_HOME`
|
||||
|
||||
| `loader.args`
|
||||
| `Loader-Args`
|
||||
| `LOADER_ARGS`
|
||||
|
||||
| `loader.main`
|
||||
| `Start-Class`
|
||||
| `LOADER_MAIN`
|
||||
|
||||
| `loader.config.location`
|
||||
| `Loader-Config-Location`
|
||||
| `LOADER_CONFIG_LOCATION`
|
||||
|
||||
| `loader.system`
|
||||
| `Loader-System`
|
||||
| `LOADER_SYSTEM`
|
||||
|===
|
||||
|
||||
TIP: Build plugins automatically move the `Main-Class` attribute to `Start-Class` when the fat jar is built.
|
||||
If you use that, specify the name of the class to launch by using the `Main-Class` attribute and leaving out `Start-Class`.
|
||||
|
||||
The following rules apply to working with `PropertiesLauncher`:
|
||||
|
||||
* `loader.properties` is searched for in `loader.home`, then in the root of the classpath, and then in `classpath:/BOOT-INF/classes`.
|
||||
The first location where a file with that name exists is used.
|
||||
* `loader.home` is the directory location of an additional properties file (overriding the default) only when `loader.config.location` is not specified.
|
||||
* `loader.path` can contain directories (which are scanned recursively for jar and zip files), archive paths, a directory within an archive that is scanned for jar files (for example, `dependencies.jar!/lib`), or wildcard patterns (for the default JVM behavior).
|
||||
Archive paths can be relative to `loader.home` or anywhere in the file system with a `jar:file:` prefix.
|
||||
* `loader.path` (if empty) defaults to `BOOT-INF/lib` (meaning a local directory or a nested one if running from an archive).
|
||||
Because of this, `PropertiesLauncher` behaves the same as `JarLauncher` when no additional configuration is provided.
|
||||
* `loader.path` can not be used to configure the location of `loader.properties` (the classpath used to search for the latter is the JVM classpath when `PropertiesLauncher` is launched).
|
||||
* Placeholder replacement is done from System and environment variables plus the properties file itself on all values before use.
|
||||
* The search order for properties (where it makes sense to look in more than one place) is environment variables, system properties, `loader.properties`, the exploded archive manifest, and the archive manifest.
|
||||
|
||||
|
||||
|
||||
[[appendix.executable-jar.restrictions]]
|
||||
== Executable Jar Restrictions
|
||||
You need to consider the following restrictions when working with a Spring Boot Loader packaged application:
|
||||
|
||||
|
||||
|
||||
[[appendix.executable-jar-zip-entry-compression]]
|
||||
* Zip entry compression:
|
||||
The `ZipEntry` for a nested jar must be saved by using the `ZipEntry.STORED` method.
|
||||
This is required so that we can seek directly to individual content within the nested jar.
|
||||
The content of the nested jar file itself can still be compressed, as can any other entries in the outer jar.
|
||||
|
||||
|
||||
|
||||
[[appendix.executable-jar-system-classloader]]
|
||||
* System classLoader:
|
||||
Launched applications should use `Thread.getContextClassLoader()` when loading classes (most libraries and frameworks do so by default).
|
||||
Trying to load nested jar classes with `ClassLoader.getSystemClassLoader()` fails.
|
||||
`java.util.Logging` always uses the system classloader.
|
||||
For this reason, you should consider a different logging implementation.
|
||||
|
||||
|
||||
|
||||
[[appendix.executable-jar.alternatives]]
|
||||
== Alternative Single Jar Solutions
|
||||
If the preceding restrictions mean that you cannot use Spring Boot Loader, consider the following alternatives:
|
||||
|
||||
* https://maven.apache.org/plugins/maven-shade-plugin/[Maven Shade Plugin]
|
||||
* http://www.jdotsoft.com/JarClassLoader.php[JarClassLoader]
|
||||
* https://sourceforge.net/projects/one-jar/[OneJar]
|
||||
* https://imperceptiblethoughts.com/shadow/[Gradle Shadow Plugin]
|
||||
include::executable-jar/restrictions.adoc[]
|
||||
|
||||
include::executable-jar/alternatives.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
[[executable-jar.alternatives]]
|
||||
== Alternative Single Jar Solutions
|
||||
If the preceding restrictions mean that you cannot use Spring Boot Loader, consider the following alternatives:
|
||||
|
||||
* https://maven.apache.org/plugins/maven-shade-plugin/[Maven Shade Plugin]
|
||||
* http://www.jdotsoft.com/JarClassLoader.php[JarClassLoader]
|
||||
* https://sourceforge.net/projects/one-jar/[OneJar]
|
||||
* https://imperceptiblethoughts.com/shadow/[Gradle Shadow Plugin]
|
||||
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
[[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.
|
||||
When first loaded, the location of each `JarEntry` is mapped to a physical file offset of the outer jar, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
myapp.jar
|
||||
+-------------------+-------------------------+
|
||||
| /BOOT-INF/classes | /BOOT-INF/lib/mylib.jar |
|
||||
|+-----------------+||+-----------+----------+|
|
||||
|| A.class ||| B.class | C.class ||
|
||||
|+-----------------+||+-----------+----------+|
|
||||
+-------------------+-------------------------+
|
||||
^ ^ ^
|
||||
0063 3452 3980
|
||||
----
|
||||
|
||||
The preceding example shows how `A.class` can be found in `/BOOT-INF/classes` in `myapp.jar` at position `0063`.
|
||||
`B.class` from the nested jar can actually be found in `myapp.jar` at position `3452`, and `C.class` is at position `3980`.
|
||||
|
||||
Armed with this information, we can load specific nested entries by seeking to the appropriate part of the outer jar.
|
||||
We do not need to unpack the archive, and we do not need to read all entry data into memory.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
The `getURL()` method returns a `URL` that opens a connection compatible with `java.net.JarURLConnection` and can be used with Java's `URLClassLoader`.
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
[[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.
|
||||
|
||||
There are three launcher subclasses (`JarLauncher`, `WarLauncher`, and `PropertiesLauncher`).
|
||||
Their purpose is to load resources (`.class` files and so on) from nested jar files or war files in directories (as opposed to those explicitly on the classpath).
|
||||
In the case of `JarLauncher` and `WarLauncher`, the nested paths are fixed.
|
||||
`JarLauncher` looks in `BOOT-INF/lib/`, and `WarLauncher` looks in `WEB-INF/lib/` and `WEB-INF/lib-provided/`.
|
||||
You can add extra jars in those locations if you want more.
|
||||
The `PropertiesLauncher` looks in `BOOT-INF/lib/` in your application archive by default.
|
||||
You can add additional locations by setting an environment variable called `LOADER_PATH` or `loader.path` in `loader.properties` (which is a comma-separated list of directories, archives, or directories within archives).
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
|
||||
The following example shows a typical `MANIFEST.MF` for an executable jar file:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
Main-Class: org.springframework.boot.loader.JarLauncher
|
||||
Start-Class: com.mycompany.project.MyApplication
|
||||
----
|
||||
|
||||
For a war file, it would be as follows:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
Main-Class: org.springframework.boot.loader.WarLauncher
|
||||
Start-Class: com.mycompany.project.MyApplication
|
||||
----
|
||||
|
||||
NOTE: You need not specify `Class-Path` entries in your manifest file.
|
||||
The classpath is deduced from the nested jars.
|
||||
|
|
@ -0,0 +1,141 @@
|
|||
[[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.
|
||||
|
||||
To solve this problem, many developers use "`shaded`" jars.
|
||||
A shaded jar packages all classes, from all jars, into a single "`uber jar`".
|
||||
The problem with shaded jars is that it becomes hard to see which libraries are actually in your application.
|
||||
It can also be problematic if the same filename is used (but with different content) in multiple jars.
|
||||
Spring Boot takes a different approach and lets you actually nest jars directly.
|
||||
|
||||
|
||||
|
||||
[[executable-jar.nested-jars.jar-structure]]
|
||||
=== The Executable Jar File Structure
|
||||
Spring Boot Loader-compatible jar files should be structured in the following way:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
example.jar
|
||||
|
|
||||
+-META-INF
|
||||
| +-MANIFEST.MF
|
||||
+-org
|
||||
| +-springframework
|
||||
| +-boot
|
||||
| +-loader
|
||||
| +-<spring boot loader classes>
|
||||
+-BOOT-INF
|
||||
+-classes
|
||||
| +-mycompany
|
||||
| +-project
|
||||
| +-YourClasses.class
|
||||
+-lib
|
||||
+-dependency1.jar
|
||||
+-dependency2.jar
|
||||
----
|
||||
|
||||
Application classes should be placed in a nested `BOOT-INF/classes` directory.
|
||||
Dependencies should be placed in a nested `BOOT-INF/lib` directory.
|
||||
|
||||
|
||||
|
||||
[[executable-jar.nested-jars.war-structure]]
|
||||
=== The Executable War File Structure
|
||||
Spring Boot Loader-compatible war files should be structured in the following way:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
example.war
|
||||
|
|
||||
+-META-INF
|
||||
| +-MANIFEST.MF
|
||||
+-org
|
||||
| +-springframework
|
||||
| +-boot
|
||||
| +-loader
|
||||
| +-<spring boot loader classes>
|
||||
+-WEB-INF
|
||||
+-classes
|
||||
| +-com
|
||||
| +-mycompany
|
||||
| +-project
|
||||
| +-YourClasses.class
|
||||
+-lib
|
||||
| +-dependency1.jar
|
||||
| +-dependency2.jar
|
||||
+-lib-provided
|
||||
+-servlet-api.jar
|
||||
+-dependency3.jar
|
||||
----
|
||||
|
||||
Dependencies should be placed in a nested `WEB-INF/lib` directory.
|
||||
Any dependencies that are required when running embedded but are not required when deploying to a traditional web container should be placed in `WEB-INF/lib-provided`.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
The `layers.idx` file can be used only for jars, and it allows a jar to be split into logical layers for Docker/OCI image creation.
|
||||
|
||||
Index files follow a YAML compatible syntax so that they can be easily parsed by third-party tools.
|
||||
These files, however, are _not_ parsed internally as YAML and they must be written in exactly the formats described below in order to be used.
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
Each line must start with dash space (`"-·"`) and names must be in double quotes.
|
||||
|
||||
For example, given the following jar:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
example.jar
|
||||
|
|
||||
+-META-INF
|
||||
| +-...
|
||||
+-BOOT-INF
|
||||
+-classes
|
||||
| +...
|
||||
+-lib
|
||||
+-dependency1.jar
|
||||
+-dependency2.jar
|
||||
----
|
||||
|
||||
The index file would look like this:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
- "BOOT-INF/lib/dependency2.jar"
|
||||
- "BOOT-INF/lib/dependency1.jar"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[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.
|
||||
Layers are written in the order that they should be added to the Docker/OCI image.
|
||||
Layers names are written as quoted strings prefixed with dash space (`"-·"`) and with a colon (`":"`) suffix.
|
||||
Layer content is either a file or directory name written as a quoted string prefixed by space space dash space (`"··-·"`).
|
||||
A directory name ends with `/`, a file name does not.
|
||||
When a directory name is used it means that all files inside that directory are in the same layer.
|
||||
|
||||
A typical example of a layers index would be:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
- "dependencies":
|
||||
- "BOOT-INF/lib/dependency1.jar"
|
||||
- "BOOT-INF/lib/dependency2.jar"
|
||||
- "application":
|
||||
- "BOOT-INF/classes/"
|
||||
- "META-INF/"
|
||||
----
|
||||
|
|
@ -0,0 +1,81 @@
|
|||
[[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:
|
||||
|
||||
|===
|
||||
| Key | Purpose
|
||||
|
||||
| `loader.path`
|
||||
| Comma-separated Classpath, such as `lib,$\{HOME}/app/lib`.
|
||||
Earlier entries take precedence, like a regular `-classpath` on the `javac` command line.
|
||||
|
||||
| `loader.home`
|
||||
| Used to resolve relative paths in `loader.path`.
|
||||
For example, given `loader.path=lib`, then `${loader.home}/lib` is a classpath location (along with all jar files in that directory).
|
||||
This property is also used to locate a `loader.properties` file, as in the following example `file:///opt/app` It defaults to `${user.dir}`.
|
||||
|
||||
| `loader.args`
|
||||
| Default arguments for the main method (space separated).
|
||||
|
||||
| `loader.main`
|
||||
| Name of main class to launch (for example, `com.app.Application`).
|
||||
|
||||
| `loader.config.name`
|
||||
| Name of properties file (for example, `launcher`).
|
||||
It defaults to `loader`.
|
||||
|
||||
| `loader.config.location`
|
||||
| Path to properties file (for example, `classpath:loader.properties`).
|
||||
It defaults to `loader.properties`.
|
||||
|
||||
| `loader.system`
|
||||
| Boolean flag to indicate that all properties should be added to System properties.
|
||||
It defaults to `false`.
|
||||
|===
|
||||
|
||||
When specified as environment variables or manifest entries, the following names should be used:
|
||||
|
||||
|===
|
||||
| Key | Manifest entry | Environment variable
|
||||
|
||||
| `loader.path`
|
||||
| `Loader-Path`
|
||||
| `LOADER_PATH`
|
||||
|
||||
| `loader.home`
|
||||
| `Loader-Home`
|
||||
| `LOADER_HOME`
|
||||
|
||||
| `loader.args`
|
||||
| `Loader-Args`
|
||||
| `LOADER_ARGS`
|
||||
|
||||
| `loader.main`
|
||||
| `Start-Class`
|
||||
| `LOADER_MAIN`
|
||||
|
||||
| `loader.config.location`
|
||||
| `Loader-Config-Location`
|
||||
| `LOADER_CONFIG_LOCATION`
|
||||
|
||||
| `loader.system`
|
||||
| `Loader-System`
|
||||
| `LOADER_SYSTEM`
|
||||
|===
|
||||
|
||||
TIP: Build plugins automatically move the `Main-Class` attribute to `Start-Class` when the fat jar is built.
|
||||
If you use that, specify the name of the class to launch by using the `Main-Class` attribute and leaving out `Start-Class`.
|
||||
|
||||
The following rules apply to working with `PropertiesLauncher`:
|
||||
|
||||
* `loader.properties` is searched for in `loader.home`, then in the root of the classpath, and then in `classpath:/BOOT-INF/classes`.
|
||||
The first location where a file with that name exists is used.
|
||||
* `loader.home` is the directory location of an additional properties file (overriding the default) only when `loader.config.location` is not specified.
|
||||
* `loader.path` can contain directories (which are scanned recursively for jar and zip files), archive paths, a directory within an archive that is scanned for jar files (for example, `dependencies.jar!/lib`), or wildcard patterns (for the default JVM behavior).
|
||||
Archive paths can be relative to `loader.home` or anywhere in the file system with a `jar:file:` prefix.
|
||||
* `loader.path` (if empty) defaults to `BOOT-INF/lib` (meaning a local directory or a nested one if running from an archive).
|
||||
Because of this, `PropertiesLauncher` behaves the same as `JarLauncher` when no additional configuration is provided.
|
||||
* `loader.path` can not be used to configure the location of `loader.properties` (the classpath used to search for the latter is the JVM classpath when `PropertiesLauncher` is launched).
|
||||
* Placeholder replacement is done from System and environment variables plus the properties file itself on all values before use.
|
||||
* The search order for properties (where it makes sense to look in more than one place) is environment variables, system properties, `loader.properties`, the exploded archive manifest, and the archive manifest.
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
[[executable-jar.restrictions]]
|
||||
== Executable Jar Restrictions
|
||||
You need to consider the following restrictions when working with a Spring Boot Loader packaged application:
|
||||
|
||||
|
||||
|
||||
[[executable-jar-zip-entry-compression]]
|
||||
* Zip entry compression:
|
||||
The `ZipEntry` for a nested jar must be saved by using the `ZipEntry.STORED` method.
|
||||
This is required so that we can seek directly to individual content within the nested jar.
|
||||
The content of the nested jar file itself can still be compressed, as can any other entries in the outer jar.
|
||||
|
||||
|
||||
|
||||
[[executable-jar-system-classloader]]
|
||||
* System classLoader:
|
||||
Launched applications should use `Thread.getContextClassLoader()` when loading classes (most libraries and frameworks do so by default).
|
||||
Trying to load nested jar classes with `ClassLoader.getSystemClassLoader()` fails.
|
||||
`java.util.Logging` always uses the system classloader.
|
||||
For this reason, you should consider a different logging implementation.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,272 @@
|
|||
[[features.caching]]
|
||||
== Caching
|
||||
The Spring Framework provides support for transparently adding caching to an application.
|
||||
At its core, the abstraction applies caching to methods, thus reducing the number of executions based on the information available in the cache.
|
||||
The caching logic is applied transparently, without any interference to the invoker.
|
||||
Spring Boot auto-configures the cache infrastructure as long as caching support is enabled via the `@EnableCaching` annotation.
|
||||
|
||||
NOTE: Check the {spring-framework-docs}/integration.html#cache[relevant section] of the Spring Framework reference for more details.
|
||||
|
||||
In a nutshell, to add caching to an operation of your service add the relevant annotation to its method, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/caching/MathService.java[]
|
||||
----
|
||||
|
||||
This example demonstrates the use of caching on a potentially costly operation.
|
||||
Before invoking `computePiDecimal`, the abstraction looks for an entry in the `piDecimals` cache that matches the `i` argument.
|
||||
If an entry is found, the content in the cache is immediately returned to the caller, and the method is not invoked.
|
||||
Otherwise, the method is invoked, and the cache is updated before returning the value.
|
||||
|
||||
CAUTION: You can also use the standard JSR-107 (JCache) annotations (such as `@CacheResult`) transparently.
|
||||
However, we strongly advise you to not mix and match the Spring Cache and JCache annotations.
|
||||
|
||||
If you do not add any specific cache library, Spring Boot auto-configures a <<features#features.caching.provider.simple,simple provider>> that uses concurrent maps in memory.
|
||||
When a cache is required (such as `piDecimals` in the preceding example), this provider creates it for you.
|
||||
The simple provider is not really recommended for production usage, but it is great for getting started and making sure that you understand the features.
|
||||
When you have made up your mind about the cache provider to use, please make sure to read its documentation to figure out how to configure the caches that your application uses.
|
||||
Nearly all providers require you to explicitly configure every cache that you use in the application.
|
||||
Some offer a way to customize the default caches defined by the configprop:spring.cache.cache-names[] property.
|
||||
|
||||
TIP: It is also possible to transparently {spring-framework-docs}/integration.html#cache-annotations-put[update] or {spring-framework-docs}/integration.html#cache-annotations-evict[evict] data from the cache.
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider]]
|
||||
=== Supported Cache Providers
|
||||
The cache abstraction does not provide an actual store and relies on abstraction materialized by the `org.springframework.cache.Cache` and `org.springframework.cache.CacheManager` interfaces.
|
||||
|
||||
If you have not defined a bean of type `CacheManager` or a `CacheResolver` named `cacheResolver` (see {spring-framework-api}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`]), Spring Boot tries to detect the following providers (in the indicated order):
|
||||
|
||||
. <<features#features.caching.provider.generic,Generic>>
|
||||
. <<features#features.caching.provider.jcache,JCache (JSR-107)>> (EhCache 3, Hazelcast, Infinispan, and others)
|
||||
. <<features#features.caching.provider.ehcache2,EhCache 2.x>>
|
||||
. <<features#features.caching.provider.hazelcast,Hazelcast>>
|
||||
. <<features#features.caching.provider.infinispan,Infinispan>>
|
||||
. <<features#features.caching.provider.couchbase,Couchbase>>
|
||||
. <<features#features.caching.provider.redis,Redis>>
|
||||
. <<features#features.caching.provider.caffeine,Caffeine>>
|
||||
. <<features#features.caching.provider.simple,Simple>>
|
||||
|
||||
TIP: It is also possible to _force_ a particular cache provider by setting the configprop:spring.cache.type[] property.
|
||||
Use this property if you need to <<features#features.caching.provider.none,disable caching altogether>> in certain environment (such as tests).
|
||||
|
||||
TIP: Use the `spring-boot-starter-cache` "`Starter`" to quickly add basic caching dependencies.
|
||||
The starter brings in `spring-context-support`.
|
||||
If you add dependencies manually, you must include `spring-context-support` in order to use the JCache, EhCache 2.x, or Caffeine support.
|
||||
|
||||
If the `CacheManager` is auto-configured by Spring Boot, you can further tune its configuration before it is fully initialized by exposing a bean that implements the `CacheManagerCustomizer` interface.
|
||||
The following example sets a flag to say that `null` values should be passed down to the underlying map:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/caching/CacheManagerCustomizerConfiguration.java[]
|
||||
----
|
||||
|
||||
NOTE: In the preceding example, an auto-configured `ConcurrentMapCacheManager` is expected.
|
||||
If that is not the case (either you provided your own config or a different cache provider was auto-configured), the customizer is not invoked at all.
|
||||
You can have as many customizers as you want, and you can also order them by using `@Order` or `Ordered`.
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.generic]]
|
||||
==== Generic
|
||||
Generic caching is used if the context defines _at least_ one `org.springframework.cache.Cache` bean.
|
||||
A `CacheManager` wrapping all beans of that type is created.
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.jcache]]
|
||||
==== JCache (JSR-107)
|
||||
https://jcp.org/en/jsr/detail?id=107[JCache] is bootstrapped through the presence of a `javax.cache.spi.CachingProvider` on the classpath (that is, a JSR-107 compliant caching library exists on the classpath), and the `JCacheCacheManager` is provided by the `spring-boot-starter-cache` "`Starter`".
|
||||
Various compliant libraries are available, and Spring Boot provides dependency management for Ehcache 3, Hazelcast, and Infinispan.
|
||||
Any other compliant library can be added as well.
|
||||
|
||||
It might happen that more than one provider is present, in which case the provider must be explicitly specified.
|
||||
Even if the JSR-107 standard does not enforce a standardized way to define the location of the configuration file, Spring Boot does its best to accommodate setting a cache with implementation details, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
# Only necessary if more than one provider is present
|
||||
spring:
|
||||
cache:
|
||||
jcache:
|
||||
provider: "com.acme.MyCachingProvider"
|
||||
config: "classpath:acme.xml"
|
||||
----
|
||||
|
||||
NOTE: When a cache library offers both a native implementation and JSR-107 support, Spring Boot prefers the JSR-107 support, so that the same features are available if you switch to a different JSR-107 implementation.
|
||||
|
||||
TIP: Spring Boot has <<features#features.hazelcast,general support for Hazelcast>>.
|
||||
If a single `HazelcastInstance` is available, it is automatically reused for the `CacheManager` as well, unless the configprop:spring.cache.jcache.config[] property is specified.
|
||||
|
||||
There are two ways to customize the underlying `javax.cache.cacheManager`:
|
||||
|
||||
* Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property.
|
||||
If a custom `javax.cache.configuration.Configuration` bean is defined, it is used to customize them.
|
||||
* `org.springframework.boot.autoconfigure.cache.JCacheManagerCustomizer` beans are invoked with the reference of the `CacheManager` for full customization.
|
||||
|
||||
TIP: If a standard `javax.cache.CacheManager` bean is defined, it is wrapped automatically in an `org.springframework.cache.CacheManager` implementation that the abstraction expects.
|
||||
No further customization is applied to it.
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.ehcache2]]
|
||||
==== EhCache 2.x
|
||||
https://www.ehcache.org/[EhCache] 2.x is used if a file named `ehcache.xml` can be found at the root of the classpath.
|
||||
If EhCache 2.x is found, the `EhCacheCacheManager` provided by the `spring-boot-starter-cache` "`Starter`" is used to bootstrap the cache manager.
|
||||
An alternate configuration file can be provided as well, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
cache:
|
||||
ehcache:
|
||||
config: "classpath:config/another-config.xml"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.hazelcast]]
|
||||
==== Hazelcast
|
||||
Spring Boot has <<features#features.hazelcast,general support for Hazelcast>>.
|
||||
If a `HazelcastInstance` has been auto-configured, it is automatically wrapped in a `CacheManager`.
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.infinispan]]
|
||||
==== Infinispan
|
||||
https://infinispan.org/[Infinispan] has no default configuration file location, so it must be specified explicitly.
|
||||
Otherwise, the default bootstrap is used.
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
cache:
|
||||
infinispan:
|
||||
config: "infinispan.xml"
|
||||
----
|
||||
|
||||
Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property.
|
||||
If a custom `ConfigurationBuilder` bean is defined, it is used to customize the caches.
|
||||
|
||||
NOTE: The support of Infinispan in Spring Boot is restricted to the embedded mode and is quite basic.
|
||||
If you want more options, you should use the official Infinispan Spring Boot starter instead.
|
||||
See https://github.com/infinispan/infinispan-spring-boot[Infinispan's documentation] for more details.
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.couchbase]]
|
||||
==== Couchbase
|
||||
If Spring Data Couchbase is available and Couchbase is <<features#features.nosql.couchbase,configured>>, a `CouchbaseCacheManager` is auto-configured.
|
||||
It is possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property and cache defaults can be configured by using `spring.cache.couchbase.*` properties.
|
||||
For instance, the following configuration creates `cache1` and `cache2` caches with an entry _expiration_ of 10 minutes:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
cache:
|
||||
cache-names: "cache1,cache2"
|
||||
couchbase:
|
||||
expiration: "10m"
|
||||
----
|
||||
|
||||
If you need more control over the configuration, consider registering a `CouchbaseCacheManagerBuilderCustomizer` bean.
|
||||
The following example shows a customizer that configures a specific entry expiration for `cache1` and `cache2`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/CouchbaseCacheManagerConfiguration.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.redis]]
|
||||
==== Redis
|
||||
If https://redis.io/[Redis] is available and configured, a `RedisCacheManager` is auto-configured.
|
||||
It is possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property and cache defaults can be configured by using `spring.cache.redis.*` properties.
|
||||
For instance, the following configuration creates `cache1` and `cache2` caches with a _time to live_ of 10 minutes:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
cache:
|
||||
cache-names: "cache1,cache2"
|
||||
redis:
|
||||
time-to-live: "10m"
|
||||
----
|
||||
|
||||
NOTE: By default, a key prefix is added so that, if two separate caches use the same key, Redis does not have overlapping keys and cannot return invalid values.
|
||||
We strongly recommend keeping this setting enabled if you create your own `RedisCacheManager`.
|
||||
|
||||
TIP: You can take full control of the default configuration by adding a `RedisCacheConfiguration` `@Bean` of your own.
|
||||
This can be useful if you're looking for customizing the default serialization strategy.
|
||||
|
||||
If you need more control over the configuration, consider registering a `RedisCacheManagerBuilderCustomizer` bean.
|
||||
The following example shows a customizer that configures a specific time to live for `cache1` and `cache2`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/RedisCacheManagerConfiguration.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.caffeine]]
|
||||
==== Caffeine
|
||||
https://github.com/ben-manes/caffeine[Caffeine] is a Java 8 rewrite of Guava's cache that supersedes support for Guava.
|
||||
If Caffeine is present, a `CaffeineCacheManager` (provided by the `spring-boot-starter-cache` "`Starter`") is auto-configured.
|
||||
Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property and can be customized by one of the following (in the indicated order):
|
||||
|
||||
. A cache spec defined by `spring.cache.caffeine.spec`
|
||||
. A `com.github.benmanes.caffeine.cache.CaffeineSpec` bean is defined
|
||||
. A `com.github.benmanes.caffeine.cache.Caffeine` bean is defined
|
||||
|
||||
For instance, the following configuration creates `cache1` and `cache2` caches with a maximum size of 500 and a _time to live_ of 10 minutes
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
cache:
|
||||
cache-names: "cache1,cache2"
|
||||
caffeine:
|
||||
spec: "maximumSize=500,expireAfterAccess=600s"
|
||||
----
|
||||
|
||||
If a `com.github.benmanes.caffeine.cache.CacheLoader` bean is defined, it is automatically associated to the `CaffeineCacheManager`.
|
||||
Since the `CacheLoader` is going to be associated with _all_ caches managed by the cache manager, it must be defined as `CacheLoader<Object, Object>`.
|
||||
The auto-configuration ignores any other generic type.
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.simple]]
|
||||
==== Simple
|
||||
If none of the other providers can be found, a simple implementation using a `ConcurrentHashMap` as the cache store is configured.
|
||||
This is the default if no caching library is present in your application.
|
||||
By default, caches are created as needed, but you can restrict the list of available caches by setting the `cache-names` property.
|
||||
For instance, if you want only `cache1` and `cache2` caches, set the `cache-names` property as follows:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
cache:
|
||||
cache-names: "cache1,cache2"
|
||||
----
|
||||
|
||||
If you do so and your application uses a cache not listed, then it fails at runtime when the cache is needed, but not on startup.
|
||||
This is similar to the way the "real" cache providers behave if you use an undeclared cache.
|
||||
|
||||
|
||||
|
||||
[[features.caching.provider.none]]
|
||||
==== None
|
||||
When `@EnableCaching` is present in your configuration, a suitable cache configuration is expected as well.
|
||||
If you need to disable caching altogether in certain environments, force the cache type to `none` to use a no-op implementation, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
cache:
|
||||
type: "none"
|
||||
----
|
||||
|
|
@ -0,0 +1,138 @@
|
|||
[[features.container-images]]
|
||||
== Container Images
|
||||
It is easily possible to package a Spring Boot fat jar as a docker image.
|
||||
However, there are various downsides to copying and running the fat jar as is in the docker image.
|
||||
There’s always a certain amount of overhead when running a fat jar without unpacking it, and in a containerized environment this can be noticeable.
|
||||
The other issue is that putting your application's code and all its dependencies in one layer in the Docker image is sub-optimal.
|
||||
Since you probably recompile your code more often than you upgrade the version of Spring Boot you use, it’s often better to separate things a bit more.
|
||||
If you put jar files in the layer before your application classes, Docker often only needs to change the very bottom layer and can pick others up from its cache.
|
||||
|
||||
|
||||
|
||||
[[features.container-images.layering]]
|
||||
=== Layering Docker Images
|
||||
To make it easier to create optimized Docker images, Spring Boot supports adding a layer index file to the jar.
|
||||
It provides a list of layers and the parts of the jar that should be contained within them.
|
||||
The list of layers in the index is ordered based on the order in which the layers should be added to the Docker/OCI image.
|
||||
Out-of-the-box, the following layers are supported:
|
||||
|
||||
* `dependencies` (for regular released dependencies)
|
||||
* `spring-boot-loader` (for everything under `org/springframework/boot/loader`)
|
||||
* `snapshot-dependencies` (for snapshot dependencies)
|
||||
* `application` (for application classes and resources)
|
||||
|
||||
The following shows an example of a `layers.idx` file:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
- "dependencies":
|
||||
- BOOT-INF/lib/library1.jar
|
||||
- BOOT-INF/lib/library2.jar
|
||||
- "spring-boot-loader":
|
||||
- org/springframework/boot/loader/JarLauncher.class
|
||||
- org/springframework/boot/loader/jar/JarEntry.class
|
||||
- "snapshot-dependencies":
|
||||
- BOOT-INF/lib/library3-SNAPSHOT.jar
|
||||
- "application":
|
||||
- META-INF/MANIFEST.MF
|
||||
- BOOT-INF/classes/a/b/C.class
|
||||
----
|
||||
|
||||
This layering is designed to separate code based on how likely it is to change between application builds.
|
||||
Library code is less likely to change between builds, so it is placed in its own layers to allow tooling to re-use the layers from cache.
|
||||
Application code is more likely to change between builds so it is isolated in a separate layer.
|
||||
|
||||
Spring Boot also supports layering for war files with the help of a `layers.idx`.
|
||||
|
||||
For Maven, refer to the {spring-boot-maven-plugin-docs}#repackage-layers[packaging layered jar or war section] for more details on adding a layer index to the archive.
|
||||
For Gradle, refer to the {spring-boot-gradle-plugin-docs}#packaging-layered-archives[packaging layered jar or war section] of the Gradle plugin documentation.
|
||||
|
||||
|
||||
|
||||
[[features.container-images.building]]
|
||||
=== Building Container Images
|
||||
Spring Boot applications can be containerized <<features#features.container-images.building.dockerfiles,using Dockerfiles>>, or by <<features#features.container-images.building.buildpacks,using Cloud Native Buildpacks to create docker compatible container images that you can run anywhere>>.
|
||||
|
||||
|
||||
|
||||
[[features.container-images.building.dockerfiles]]
|
||||
==== Dockerfiles
|
||||
While it is possible to convert a Spring Boot fat jar into a docker image with just a few lines in the Dockerfile, we will use the <<features#features.container-images.layering,layering feature>> to create an optimized docker image.
|
||||
When you create a jar containing the layers index file, the `spring-boot-jarmode-layertools` jar will be added as a dependency to your jar.
|
||||
With this jar on the classpath, you can launch your application in a special mode which allows the bootstrap code to run something entirely different from your application, for example, something that extracts the layers.
|
||||
|
||||
CAUTION: The `layertools` mode can not be used with a <<deployment#deployment.installing, fully executable Spring Boot archive>> that includes a launch script.
|
||||
Disable launch script configuration when building a jar file that is intended to be used with `layertools`.
|
||||
|
||||
Here’s how you can launch your jar with a `layertools` jar mode:
|
||||
|
||||
----
|
||||
$ java -Djarmode=layertools -jar my-app.jar
|
||||
----
|
||||
|
||||
This will provide the following output:
|
||||
|
||||
----
|
||||
Usage:
|
||||
java -Djarmode=layertools -jar my-app.jar
|
||||
|
||||
Available commands:
|
||||
list List layers from the jar that can be extracted
|
||||
extract Extracts layers from the jar for image creation
|
||||
help Help about any command
|
||||
----
|
||||
|
||||
The `extract` command can be used to easily split the application into layers to be added to the dockerfile.
|
||||
Here's an example of a Dockerfile using `jarmode`.
|
||||
|
||||
----
|
||||
FROM adoptopenjdk:11-jre-hotspot as builder
|
||||
WORKDIR application
|
||||
ARG JAR_FILE=target/*.jar
|
||||
COPY ${JAR_FILE} application.jar
|
||||
RUN java -Djarmode=layertools -jar application.jar extract
|
||||
|
||||
FROM adoptopenjdk:11-jre-hotspot
|
||||
WORKDIR application
|
||||
COPY --from=builder application/dependencies/ ./
|
||||
COPY --from=builder application/spring-boot-loader/ ./
|
||||
COPY --from=builder application/snapshot-dependencies/ ./
|
||||
COPY --from=builder application/application/ ./
|
||||
ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"]
|
||||
----
|
||||
|
||||
Assuming the above `Dockerfile` is in the current directory, your docker image can be built with `docker build .`, or optionally specifying the path to your application jar, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
docker build --build-arg JAR_FILE=path/to/myapp.jar .
|
||||
----
|
||||
|
||||
This is a multi-stage dockerfile.
|
||||
The builder stage extracts the directories that are needed later.
|
||||
Each of the `COPY` commands relates to the layers extracted by the jarmode.
|
||||
|
||||
Of course, a Dockerfile can be written without using the jarmode.
|
||||
You can use some combination of `unzip` and `mv` to move things to the right layer but jarmode simplifies that.
|
||||
|
||||
|
||||
|
||||
[[features.container-images.building.buildpacks]]
|
||||
==== Cloud Native Buildpacks
|
||||
Dockerfiles are just one way to build docker images.
|
||||
Another way to build docker images is directly from your Maven or Gradle plugin, using buildpacks.
|
||||
If you’ve ever used an application platform such as Cloud Foundry or Heroku then you’ve probably used a buildpack.
|
||||
Buildpacks are the part of the platform that takes your application and converts it into something that the platform can actually run.
|
||||
For example, Cloud Foundry’s Java buildpack will notice that you’re pushing a `.jar` file and automatically add a relevant JRE.
|
||||
|
||||
With Cloud Native Buildpacks, you can create Docker compatible images that you can run anywhere.
|
||||
Spring Boot includes buildpack support directly for both Maven and Gradle.
|
||||
This means you can just type a single command and quickly get a sensible image into your locally running Docker daemon.
|
||||
|
||||
Refer to the individual plugin documentation on how to use buildpacks with {spring-boot-maven-plugin-docs}#build-image[Maven] and {spring-boot-gradle-plugin-docs}#build-image[Gradle].
|
||||
|
||||
NOTE: The https://github.com/paketo-buildpacks/spring-boot[Paketo Spring Boot buildpack] has also been updated to support the `layers.idx` file so any customization that is applied to it will be reflected in the image created by the buildpack.
|
||||
|
||||
NOTE: In order to achieve reproducible builds and container image caching, Buildpacks can manipulate the application resources metadata (such as the file "last modified" information).
|
||||
You should ensure that your application does not rely on that metadata at runtime.
|
||||
Spring Boot can use that information when serving static resources, but this can be disabled with configprop:spring.web.resources.cache.use-last-modified[]
|
||||
|
|
@ -0,0 +1,350 @@
|
|||
[[features.developing-auto-configuration]]
|
||||
== Creating Your Own Auto-configuration
|
||||
If you work in a company that develops shared libraries, or if you work on an open-source or commercial library, you might want to develop your own auto-configuration.
|
||||
Auto-configuration classes can be bundled in external jars and still be picked-up by Spring Boot.
|
||||
|
||||
Auto-configuration can be associated to a "`starter`" that provides the auto-configuration code as well as the typical libraries that you would use with it.
|
||||
We first cover what you need to know to build your own auto-configuration and then we move on to the <<features#features.developing-auto-configuration.custom-starter,typical steps required to create a custom starter>>.
|
||||
|
||||
TIP: A https://github.com/snicoll-demos/spring-boot-master-auto-configuration[demo project] is available to showcase how you can create a starter step-by-step.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.understanding-auto-configured-beans]]
|
||||
=== Understanding Auto-configured Beans
|
||||
Under the hood, auto-configuration is implemented with standard `@Configuration` classes.
|
||||
Additional `@Conditional` annotations are used to constrain when the auto-configuration should apply.
|
||||
Usually, auto-configuration classes use `@ConditionalOnClass` and `@ConditionalOnMissingBean` annotations.
|
||||
This ensures that auto-configuration applies only when relevant classes are found and when you have not declared your own `@Configuration`.
|
||||
|
||||
You can browse the source code of {spring-boot-autoconfigure-module-code}[`spring-boot-autoconfigure`] to see the `@Configuration` classes that Spring provides (see the {spring-boot-code}/spring-boot-project/spring-boot-autoconfigure/src/main/resources/META-INF/spring.factories[`META-INF/spring.factories`] file).
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.locating-auto-configuration-candidates]]
|
||||
=== Locating Auto-configuration Candidates
|
||||
Spring Boot checks for the presence of a `META-INF/spring.factories` file within your published jar.
|
||||
The file should list your configuration classes under the `EnableAutoConfiguration` key, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
|
||||
com.mycorp.libx.autoconfigure.LibXAutoConfiguration,\
|
||||
com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration
|
||||
----
|
||||
|
||||
NOTE: Auto-configurations must be loaded that way _only_.
|
||||
Make sure that they are defined in a specific package space and that they are never the target of component scanning.
|
||||
Furthermore, auto-configuration classes should not enable component scanning to find additional components.
|
||||
Specific ``@Import``s should be used instead.
|
||||
|
||||
You can use the {spring-boot-autoconfigure-module-code}/AutoConfigureAfter.java[`@AutoConfigureAfter`] or {spring-boot-autoconfigure-module-code}/AutoConfigureBefore.java[`@AutoConfigureBefore`] annotations if your configuration needs to be applied in a specific order.
|
||||
For example, if you provide web-specific configuration, your class may need to be applied after `WebMvcAutoConfiguration`.
|
||||
|
||||
If you want to order certain auto-configurations that should not have any direct knowledge of each other, you can also use `@AutoConfigureOrder`.
|
||||
That annotation has the same semantic as the regular `@Order` annotation but provides a dedicated order for auto-configuration classes.
|
||||
|
||||
As with standard `@Configuration` classes, the order in which auto-configuration classes are applied only affects the order in which their beans are defined.
|
||||
The order in which those beans are subsequently created is unaffected and is determined by each bean's dependencies and any `@DependsOn` relationships.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.condition-annotations]]
|
||||
=== Condition Annotations
|
||||
You almost always want to include one or more `@Conditional` annotations on your auto-configuration class.
|
||||
The `@ConditionalOnMissingBean` annotation is one common example that is used to allow developers to override auto-configuration if they are not happy with your defaults.
|
||||
|
||||
Spring Boot includes a number of `@Conditional` annotations that you can reuse in your own code by annotating `@Configuration` classes or individual `@Bean` methods.
|
||||
These annotations include:
|
||||
|
||||
* <<features#features.developing-auto-configuration.condition-annotations.class-conditions>>
|
||||
* <<features#features.developing-auto-configuration.condition-annotations.bean-conditions>>
|
||||
* <<features#features.developing-auto-configuration.condition-annotations.property-conditions>>
|
||||
* <<features#features.developing-auto-configuration.condition-annotations.resource-conditions>>
|
||||
* <<features#features.developing-auto-configuration.condition-annotations.web-application-conditions>>
|
||||
* <<features#features.developing-auto-configuration.condition-annotations.spel-conditions>>
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.condition-annotations.class-conditions]]
|
||||
==== Class Conditions
|
||||
The `@ConditionalOnClass` and `@ConditionalOnMissingClass` annotations let `@Configuration` classes be included based on the presence or absence of specific classes.
|
||||
Due to the fact that annotation metadata is parsed by using https://asm.ow2.io/[ASM], you can use the `value` attribute to refer to the real class, even though that class might not actually appear on the running application classpath.
|
||||
You can also use the `name` attribute if you prefer to specify the class name by using a `String` value.
|
||||
|
||||
This mechanism does not apply the same way to `@Bean` methods where typically the return type is the target of the condition: before the condition on the method applies, the JVM will have loaded the class and potentially processed method references which will fail if the class is not present.
|
||||
|
||||
To handle this scenario, a separate `@Configuration` class can be used to isolate the condition, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/creatingautoconfiguration/classconditions/MyAutoConfiguration.java[]
|
||||
----
|
||||
|
||||
TIP: If you use `@ConditionalOnClass` or `@ConditionalOnMissingClass` as a part of a meta-annotation to compose your own composed annotations, you must use `name` as referring to the class in such a case is not handled.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.condition-annotations.bean-conditions]]
|
||||
==== Bean Conditions
|
||||
The `@ConditionalOnBean` and `@ConditionalOnMissingBean` annotations let a bean be included based on the presence or absence of specific beans.
|
||||
You can use the `value` attribute to specify beans by type or `name` to specify beans by name.
|
||||
The `search` attribute lets you limit the `ApplicationContext` hierarchy that should be considered when searching for beans.
|
||||
|
||||
When placed on a `@Bean` method, the target type defaults to the return type of the method, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/creatingautoconfiguration/beanconditions/MyAutoConfiguration.java[]
|
||||
----
|
||||
|
||||
In the preceding example, the `myService` bean is going to be created if no bean of type `MyService` is already contained in the `ApplicationContext`.
|
||||
|
||||
TIP: You need to be very careful about the order in which bean definitions are added, as these conditions are evaluated based on what has been processed so far.
|
||||
For this reason, we recommend using only `@ConditionalOnBean` and `@ConditionalOnMissingBean` annotations on auto-configuration classes (since these are guaranteed to load after any user-defined bean definitions have been added).
|
||||
|
||||
NOTE: `@ConditionalOnBean` and `@ConditionalOnMissingBean` do not prevent `@Configuration` classes from being created.
|
||||
The only difference between using these conditions at the class level and marking each contained `@Bean` method with the annotation is that the former prevents registration of the `@Configuration` class as a bean if the condition does not match.
|
||||
|
||||
TIP: When declaring a `@Bean` method, provide as much type information as possible in the method's return type.
|
||||
For example, if your bean's concrete class implements an interface the bean method's return type should be the concrete class and not the interface.
|
||||
Providing as much type information as possible in `@Bean` methods is particularly important when using bean conditions as their evaluation can only rely upon to type information that's available in the method signature.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.condition-annotations.property-conditions]]
|
||||
==== Property Conditions
|
||||
The `@ConditionalOnProperty` annotation lets configuration be included based on a Spring Environment property.
|
||||
Use the `prefix` and `name` attributes to specify the property that should be checked.
|
||||
By default, any property that exists and is not equal to `false` is matched.
|
||||
You can also create more advanced checks by using the `havingValue` and `matchIfMissing` attributes.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.condition-annotations.resource-conditions]]
|
||||
==== Resource Conditions
|
||||
The `@ConditionalOnResource` annotation lets configuration be included only when a specific resource is present.
|
||||
Resources can be specified by using the usual Spring conventions, as shown in the following example: `file:/home/user/test.dat`.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.condition-annotations.web-application-conditions]]
|
||||
==== Web Application Conditions
|
||||
The `@ConditionalOnWebApplication` and `@ConditionalOnNotWebApplication` annotations let configuration be included depending on whether the application is a "`web application`".
|
||||
A servlet-based web application is any application that uses a Spring `WebApplicationContext`, defines a `session` scope, or has a `ConfigurableWebEnvironment`.
|
||||
A reactive web application is any application that uses a `ReactiveWebApplicationContext`, or has a `ConfigurableReactiveWebEnvironment`.
|
||||
|
||||
The `@ConditionalOnWarDeployment` annotation lets configuration be included depending on whether the application is a traditional WAR application that is deployed to a container.
|
||||
This condition will not match for applications that are run with an embedded server.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.condition-annotations.spel-conditions]]
|
||||
==== SpEL Expression Conditions
|
||||
The `@ConditionalOnExpression` annotation lets configuration be included based on the result of a {spring-framework-docs}/core.html#expressions[SpEL expression].
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.testing]]
|
||||
=== Testing your Auto-configuration
|
||||
An auto-configuration can be affected by many factors: user configuration (`@Bean` definition and `Environment` customization), condition evaluation (presence of a particular library), and others.
|
||||
Concretely, each test should create a well defined `ApplicationContext` that represents a combination of those customizations.
|
||||
`ApplicationContextRunner` provides a great way to achieve that.
|
||||
|
||||
`ApplicationContextRunner` is usually defined as a field of the test class to gather the base, common configuration.
|
||||
The following example makes sure that `UserServiceAutoConfiguration` is always invoked:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests.java[tag=runner]
|
||||
----
|
||||
|
||||
TIP: If multiple auto-configurations have to be defined, there is no need to order their declarations as they are invoked in the exact same order as when running the application.
|
||||
|
||||
Each test can use the runner to represent a particular use case.
|
||||
For instance, the sample below invokes a user configuration (`UserConfiguration`) and checks that the auto-configuration backs off properly.
|
||||
Invoking `run` provides a callback context that can be used with `AssertJ`.
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests.java[tag=test-user-config]
|
||||
----
|
||||
|
||||
It is also possible to easily customize the `Environment`, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests.java[tag=test-env]
|
||||
----
|
||||
|
||||
The runner can also be used to display the `ConditionEvaluationReport`.
|
||||
The report can be printed at `INFO` or `DEBUG` level.
|
||||
The following example shows how to use the `ConditionEvaluationReportLoggingListener` to print the report in auto-configuration tests.
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/testing/ConditionEvaluationReportTests.java[tag=*]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.testing.simulating-a-web-context]]
|
||||
==== Simulating a Web Context
|
||||
If you need to test an auto-configuration that only operates in a Servlet or Reactive web application context, use the `WebApplicationContextRunner` or `ReactiveWebApplicationContextRunner` respectively.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.testing.overriding-classpath]]
|
||||
==== Overriding the Classpath
|
||||
It is also possible to test what happens when a particular class and/or package is not present at runtime.
|
||||
Spring Boot ships with a `FilteredClassLoader` that can easily be used by the runner.
|
||||
In the following example, we assert that if `UserService` is not present, the auto-configuration is properly disabled:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests.java[tag=test-classloader]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.custom-starter]]
|
||||
=== Creating Your Own Starter
|
||||
A typical Spring Boot starter contains code to auto-configure and customize the infrastructure of a given technology, let's call that "acme".
|
||||
To make it easily extensible, a number of configuration keys in a dedicated namespace can be exposed to the environment.
|
||||
Finally, a single "starter" dependency is provided to help users get started as easily as possible.
|
||||
|
||||
Concretely, a custom starter can contain the following:
|
||||
|
||||
* The `autoconfigure` module that contains the auto-configuration code for "acme".
|
||||
* The `starter` module that provides a dependency to the `autoconfigure` module as well as "acme" and any additional dependencies that are typically useful.
|
||||
In a nutshell, adding the starter should provide everything needed to start using that library.
|
||||
|
||||
This separation in two modules is in no way necessary.
|
||||
If "acme" has several flavours, options or optional features, then it is better to separate the auto-configuration as you can clearly express the fact some features are optional.
|
||||
Besides, you have the ability to craft a starter that provides an opinion about those optional dependencies.
|
||||
At the same time, others can rely only on the `autoconfigure` module and craft their own starter with different opinions.
|
||||
|
||||
If the auto-configuration is relatively straightforward and does not have optional feature, merging the two modules in the starter is definitely an option.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.custom-starter.naming]]
|
||||
==== Naming
|
||||
You should make sure to provide a proper namespace for your starter.
|
||||
Do not start your module names with `spring-boot`, even if you use a different Maven `groupId`.
|
||||
We may offer official support for the thing you auto-configure in the future.
|
||||
|
||||
As a rule of thumb, you should name a combined module after the starter.
|
||||
For example, assume that you are creating a starter for "acme" and that you name the auto-configure module `acme-spring-boot` and the starter `acme-spring-boot-starter`.
|
||||
If you only have one module that combines the two, name it `acme-spring-boot-starter`.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.custom-starter.configuration-keys]]
|
||||
==== Configuration keys
|
||||
If your starter provides configuration keys, use a unique namespace for them.
|
||||
In particular, do not include your keys in the namespaces that Spring Boot uses (such as `server`, `management`, `spring`, and so on).
|
||||
If you use the same namespace, we may modify these namespaces in the future in ways that break your modules.
|
||||
As a rule of thumb, prefix all your keys with a namespace that you own (e.g. `acme`).
|
||||
|
||||
Make sure that configuration keys are documented by adding field javadoc for each property, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/creatingautoconfiguration/configurationkeys/AcmeProperties.java[]
|
||||
----
|
||||
|
||||
NOTE: You should only use plain text with `@ConfigurationProperties` field Javadoc, since they are not processed before being added to the JSON.
|
||||
|
||||
Here are some rules we follow internally to make sure descriptions are consistent:
|
||||
|
||||
* Do not start the description by "The" or "A".
|
||||
* For `boolean` types, start the description with "Whether" or "Enable".
|
||||
* For collection-based types, start the description with "Comma-separated list"
|
||||
* Use `java.time.Duration` rather than `long` and describe the default unit if it differs from milliseconds, e.g. "If a duration suffix is not specified, seconds will be used".
|
||||
* Do not provide the default value in the description unless it has to be determined at runtime.
|
||||
|
||||
Make sure to <<configuration-metadata#configuration-metadata.annotation-processor,trigger meta-data generation>> so that IDE assistance is available for your keys as well.
|
||||
You may want to review the generated metadata (`META-INF/spring-configuration-metadata.json`) to make sure your keys are properly documented.
|
||||
Using your own starter in a compatible IDE is also a good idea to validate that quality of the metadata.
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.custom-starter.autoconfigure-module]]
|
||||
==== The "`autoconfigure`" Module
|
||||
The `autoconfigure` module contains everything that is necessary to get started with the library.
|
||||
It may also contain configuration key definitions (such as `@ConfigurationProperties`) and any callback interface that can be used to further customize how the components are initialized.
|
||||
|
||||
TIP: You should mark the dependencies to the library as optional so that you can include the `autoconfigure` module in your projects more easily.
|
||||
If you do it that way, the library is not provided and, by default, Spring Boot backs off.
|
||||
|
||||
Spring Boot uses an annotation processor to collect the conditions on auto-configurations in a metadata file (`META-INF/spring-autoconfigure-metadata.properties`).
|
||||
If that file is present, it is used to eagerly filter auto-configurations that do not match, which will improve startup time.
|
||||
It is recommended to add the following dependency in a module that contains auto-configurations:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-autoconfigure-processor</artifactId>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
If you have defined auto-configurations directly in your application, make sure to configure the `spring-boot-maven-plugin` to prevent the `repackage` goal from adding the dependency into the fat jar:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<project>
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<configuration>
|
||||
<excludes>
|
||||
<exclude>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-autoconfigure-processor</artifactId>
|
||||
</exclude>
|
||||
</excludes>
|
||||
</configuration>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
----
|
||||
|
||||
With Gradle 4.5 and earlier, the dependency should be declared in the `compileOnly` configuration, as shown in the following example:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compileOnly "org.springframework.boot:spring-boot-autoconfigure-processor"
|
||||
}
|
||||
----
|
||||
|
||||
With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
annotationProcessor "org.springframework.boot:spring-boot-autoconfigure-processor"
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-auto-configuration.custom-starter.starter-module]]
|
||||
==== Starter Module
|
||||
The starter is really an empty jar.
|
||||
Its only purpose is to provide the necessary dependencies to work with the library.
|
||||
You can think of it as an opinionated view of what is required to get started.
|
||||
|
||||
Do not make assumptions about the project in which your starter is added.
|
||||
If the library you are auto-configuring typically requires other starters, mention them as well.
|
||||
Providing a proper set of _default_ dependencies may be hard if the number of optional dependencies is high, as you should avoid including dependencies that are unnecessary for a typical usage of the library.
|
||||
In other words, you should not include optional dependencies.
|
||||
|
||||
NOTE: Either way, your starter must reference the core Spring Boot starter (`spring-boot-starter`) directly or indirectly (i.e. no need to add it if your starter relies on another starter).
|
||||
If a project is created with only your custom starter, Spring Boot's core features will be honoured by the presence of the core starter.
|
||||
|
|
@ -0,0 +1,891 @@
|
|||
[[features.developing-web-applications]]
|
||||
== Developing Web Applications
|
||||
Spring Boot is well suited for web application development.
|
||||
You can create a self-contained HTTP server by using embedded Tomcat, Jetty, Undertow, or Netty.
|
||||
Most web applications use the `spring-boot-starter-web` module to get up and running quickly.
|
||||
You can also choose to build reactive web applications by using the `spring-boot-starter-webflux` module.
|
||||
|
||||
If you have not yet developed a Spring Boot web application, you can follow the "Hello World!" example in the _<<getting-started#getting-started.first-application, Getting started>>_ section.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc]]
|
||||
=== The "`Spring Web MVC Framework`"
|
||||
The {spring-framework-docs}/web.html#mvc[Spring Web MVC framework] (often referred to as "`Spring MVC`") is a rich "`model view controller`" web framework.
|
||||
Spring MVC lets you create special `@Controller` or `@RestController` beans to handle incoming HTTP requests.
|
||||
Methods in your controller are mapped to HTTP by using `@RequestMapping` annotations.
|
||||
|
||||
The following code shows a typical `@RestController` that serves JSON data:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/servlet/MyRestController.java[]
|
||||
----
|
||||
|
||||
Spring MVC is part of the core Spring Framework, and detailed information is available in the {spring-framework-docs}/web.html#mvc[reference documentation].
|
||||
There are also several guides that cover Spring MVC available at https://spring.io/guides.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.auto-configuration]]
|
||||
==== Spring MVC Auto-configuration
|
||||
Spring Boot provides auto-configuration for Spring MVC that works well with most applications.
|
||||
|
||||
The auto-configuration adds the following features on top of Spring's defaults:
|
||||
|
||||
* Inclusion of `ContentNegotiatingViewResolver` and `BeanNameViewResolver` beans.
|
||||
* Support for serving static resources, including support for WebJars (covered <<features#features.developing-web-applications.spring-mvc.static-content,later in this document>>)).
|
||||
* Automatic registration of `Converter`, `GenericConverter`, and `Formatter` beans.
|
||||
* Support for `HttpMessageConverters` (covered <<features#features.developing-web-applications.spring-mvc.message-converters,later in this document>>).
|
||||
* Automatic registration of `MessageCodesResolver` (covered <<features#features.developing-web-applications.spring-mvc.message-codes,later in this document>>).
|
||||
* Static `index.html` support.
|
||||
* Automatic use of a `ConfigurableWebBindingInitializer` bean (covered <<features#features.developing-web-applications.spring-mvc.binding-initializer,later in this document>>).
|
||||
|
||||
If you want to keep those Spring Boot MVC customizations and make more {spring-framework-docs}/web.html#mvc[MVC customizations] (interceptors, formatters, view controllers, and other features), you can add your own `@Configuration` class of type `WebMvcConfigurer` but *without* `@EnableWebMvc`.
|
||||
|
||||
If you want to provide custom instances of `RequestMappingHandlerMapping`, `RequestMappingHandlerAdapter`, or `ExceptionHandlerExceptionResolver`, and still keep the Spring Boot MVC customizations, you can declare a bean of type `WebMvcRegistrations` and use it to provide custom instances of those components.
|
||||
|
||||
If you want to take complete control of Spring MVC, you can add your own `@Configuration` annotated with `@EnableWebMvc`, or alternatively add your own `@Configuration`-annotated `DelegatingWebMvcConfiguration` as described in the Javadoc of `@EnableWebMvc`.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Spring MVC uses a different `ConversionService` to the one used to convert values from your `application.properties` or `application.yaml` file.
|
||||
It means that `Period`, `Duration` and `DataSize` converters are not available and that `@DurationUnit` and `@DataSizeUnit` annotations will be ignored.
|
||||
|
||||
If you want to customize the `ConversionService` used by Spring MVC, you can provide a `WebMvcConfigurer` bean with an `addFormatters` method.
|
||||
From this method you can register any converter that you like, or you can delegate to the static methods available on `ApplicationConversionService`.
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.message-converters]]
|
||||
==== HttpMessageConverters
|
||||
Spring MVC uses the `HttpMessageConverter` interface to convert HTTP requests and responses.
|
||||
Sensible defaults are included out of the box.
|
||||
For example, objects can be automatically converted to JSON (by using the Jackson library) or XML (by using the Jackson XML extension, if available, or by using JAXB if the Jackson XML extension is not available).
|
||||
By default, strings are encoded in `UTF-8`.
|
||||
|
||||
If you need to add or customize converters, you can use Spring Boot's `HttpMessageConverters` class, as shown in the following listing:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/HttpMessageConvertersConfiguration.java[]
|
||||
----
|
||||
|
||||
Any `HttpMessageConverter` bean that is present in the context is added to the list of converters.
|
||||
You can also override default converters in the same way.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.json]]
|
||||
==== Custom JSON Serializers and Deserializers
|
||||
If you use Jackson to serialize and deserialize JSON data, you might want to write your own `JsonSerializer` and `JsonDeserializer` classes.
|
||||
Custom serializers are usually https://github.com/FasterXML/jackson-docs/wiki/JacksonHowToCustomSerializers[registered with Jackson through a module], but Spring Boot provides an alternative `@JsonComponent` annotation that makes it easier to directly register Spring Beans.
|
||||
|
||||
You can use the `@JsonComponent` annotation directly on `JsonSerializer`, `JsonDeserializer` or `KeyDeserializer` implementations.
|
||||
You can also use it on classes that contain serializers/deserializers as inner classes, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/json/MyJsonComponent.java[]
|
||||
----
|
||||
|
||||
All `@JsonComponent` beans in the `ApplicationContext` are automatically registered with Jackson.
|
||||
Because `@JsonComponent` is meta-annotated with `@Component`, the usual component-scanning rules apply.
|
||||
|
||||
Spring Boot also provides {spring-boot-module-code}/jackson/JsonObjectSerializer.java[`JsonObjectSerializer`] and {spring-boot-module-code}/jackson/JsonObjectDeserializer.java[`JsonObjectDeserializer`] base classes that provide useful alternatives to the standard Jackson versions when serializing objects.
|
||||
See {spring-boot-module-api}/jackson/JsonObjectSerializer.html[`JsonObjectSerializer`] and {spring-boot-module-api}/jackson/JsonObjectDeserializer.html[`JsonObjectDeserializer`] in the Javadoc for details.
|
||||
|
||||
The example above can be rewritten to use `JsonObjectSerializer`/`JsonObjectDeserializer` as follows:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/json/object/MyJsonComponent.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.message-codes]]
|
||||
==== MessageCodesResolver
|
||||
Spring MVC has a strategy for generating error codes for rendering error messages from binding errors: `MessageCodesResolver`.
|
||||
If you set the configprop:spring.mvc.message-codes-resolver-format[] property `PREFIX_ERROR_CODE` or `POSTFIX_ERROR_CODE`, Spring Boot creates one for you (see the enumeration in {spring-framework-api}/validation/DefaultMessageCodesResolver.Format.html[`DefaultMessageCodesResolver.Format`]).
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.static-content]]
|
||||
==== Static Content
|
||||
By default, Spring Boot serves static content from a directory called `/static` (or `/public` or `/resources` or `/META-INF/resources`) in the classpath or from the root of the `ServletContext`.
|
||||
It uses the `ResourceHttpRequestHandler` from Spring MVC so that you can modify that behavior by adding your own `WebMvcConfigurer` and overriding the `addResourceHandlers` method.
|
||||
|
||||
In a stand-alone web application, the default servlet from the container is also enabled and acts as a fallback, serving content from the root of the `ServletContext` if Spring decides not to handle it.
|
||||
Most of the time, this does not happen (unless you modify the default MVC configuration), because Spring can always handle requests through the `DispatcherServlet`.
|
||||
|
||||
By default, resources are mapped on `+/**+`, but you can tune that with the configprop:spring.mvc.static-path-pattern[] property.
|
||||
For instance, relocating all resources to `/resources/**` can be achieved as follows:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
mvc:
|
||||
static-path-pattern: "/resources/**"
|
||||
----
|
||||
|
||||
You can also customize the static resource locations by using the configprop:spring.web.resources.static-locations[] property (replacing the default values with a list of directory locations).
|
||||
The root Servlet context path, `"/"`, is automatically added as a location as well.
|
||||
|
||||
In addition to the "`standard`" static resource locations mentioned earlier, a special case is made for https://www.webjars.org/[Webjars content].
|
||||
Any resources with a path in `+/webjars/**+` are served from jar files if they are packaged in the Webjars format.
|
||||
|
||||
TIP: Do not use the `src/main/webapp` directory if your application is packaged as a jar.
|
||||
Although this directory is a common standard, it works *only* with war packaging, and it is silently ignored by most build tools if you generate a jar.
|
||||
|
||||
Spring Boot also supports the advanced resource handling features provided by Spring MVC, allowing use cases such as cache-busting static resources or using version agnostic URLs for Webjars.
|
||||
|
||||
To use version agnostic URLs for Webjars, add the `webjars-locator-core` dependency.
|
||||
Then declare your Webjar.
|
||||
Using jQuery as an example, adding `"/webjars/jquery/jquery.min.js"` results in `"/webjars/jquery/x.y.z/jquery.min.js"` where `x.y.z` is the Webjar version.
|
||||
|
||||
NOTE: If you use JBoss, you need to declare the `webjars-locator-jboss-vfs` dependency instead of the `webjars-locator-core`.
|
||||
Otherwise, all Webjars resolve as a `404`.
|
||||
|
||||
To use cache busting, the following configuration configures a cache busting solution for all static resources, effectively adding a content hash, such as `<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>`, in URLs:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
web:
|
||||
resources:
|
||||
chain:
|
||||
strategy:
|
||||
content:
|
||||
enabled: true
|
||||
paths: "/**"
|
||||
----
|
||||
|
||||
NOTE: Links to resources are rewritten in templates at runtime, thanks to a `ResourceUrlEncodingFilter` that is auto-configured for Thymeleaf and FreeMarker.
|
||||
You should manually declare this filter when using JSPs.
|
||||
Other template engines are currently not automatically supported but can be with custom template macros/helpers and the use of the {spring-framework-api}/web/servlet/resource/ResourceUrlProvider.html[`ResourceUrlProvider`].
|
||||
|
||||
When loading resources dynamically with, for example, a JavaScript module loader, renaming files is not an option.
|
||||
That is why other strategies are also supported and can be combined.
|
||||
A "fixed" strategy adds a static version string in the URL without changing the file name, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
web:
|
||||
resources:
|
||||
chain:
|
||||
strategy:
|
||||
content:
|
||||
enabled: true
|
||||
paths: "/**"
|
||||
fixed:
|
||||
enabled: true
|
||||
paths: "/js/lib/"
|
||||
version: "v12"
|
||||
----
|
||||
|
||||
With this configuration, JavaScript modules located under `"/js/lib/"` use a fixed versioning strategy (`"/v12/js/lib/mymodule.js"`), while other resources still use the content one (`<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>`).
|
||||
|
||||
See {spring-boot-autoconfigure-module-code}/web/ResourceProperties.java[`ResourceProperties`] for more supported options.
|
||||
|
||||
[TIP]
|
||||
====
|
||||
This feature has been thoroughly described in a dedicated https://spring.io/blog/2014/07/24/spring-framework-4-1-handling-static-web-resources[blog post] and in Spring Framework's {spring-framework-docs}/web.html#mvc-config-static-resources[reference documentation].
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.welcome-page]]
|
||||
==== Welcome Page
|
||||
Spring Boot supports both static and templated welcome pages.
|
||||
It first looks for an `index.html` file in the configured static content locations.
|
||||
If one is not found, it then looks for an `index` template.
|
||||
If either is found, it is automatically used as the welcome page of the application.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.content-negotiation]]
|
||||
==== Path Matching and Content Negotiation
|
||||
Spring MVC can map incoming HTTP requests to handlers by looking at the request path and matching it to the mappings defined in your application (for example, `@GetMapping` annotations on Controller methods).
|
||||
|
||||
Spring Boot chooses to disable suffix pattern matching by default, which means that requests like `"GET /projects/spring-boot.json"` won't be matched to `@GetMapping("/projects/spring-boot")` mappings.
|
||||
This is considered as a {spring-framework-docs}/web.html#mvc-ann-requestmapping-suffix-pattern-match[best practice for Spring MVC applications].
|
||||
This feature was mainly useful in the past for HTTP clients which did not send proper "Accept" request headers; we needed to make sure to send the correct Content Type to the client.
|
||||
Nowadays, Content Negotiation is much more reliable.
|
||||
|
||||
There are other ways to deal with HTTP clients that don't consistently send proper "Accept" request headers.
|
||||
Instead of using suffix matching, we can use a query parameter to ensure that requests like `"GET /projects/spring-boot?format=json"` will be mapped to `@GetMapping("/projects/spring-boot")`:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configblocks]
|
||||
----
|
||||
spring:
|
||||
mvc:
|
||||
contentnegotiation:
|
||||
favor-parameter: true
|
||||
----
|
||||
|
||||
Or if you prefer to use a different parameter name:
|
||||
|
||||
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
spring:
|
||||
mvc:
|
||||
contentnegotiation:
|
||||
favor-parameter: true
|
||||
parameter-name: "myparam"
|
||||
----
|
||||
|
||||
Most standard media types are supported out-of-the-box, but you can also define new ones:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configblocks]
|
||||
----
|
||||
spring:
|
||||
mvc:
|
||||
contentnegotiation:
|
||||
media-types:
|
||||
markdown: "text/markdown"
|
||||
----
|
||||
|
||||
|
||||
|
||||
Suffix pattern matching is deprecated and will be removed in a future release.
|
||||
If you understand the caveats and would still like your application to use suffix pattern matching, the following configuration is required:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configblocks]
|
||||
----
|
||||
spring:
|
||||
mvc:
|
||||
contentnegotiation:
|
||||
favor-path-extension: true
|
||||
pathmatch:
|
||||
use-suffix-pattern: true
|
||||
----
|
||||
|
||||
Alternatively, rather than open all suffix patterns, it's more secure to only support registered suffix patterns:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configblocks]
|
||||
----
|
||||
spring:
|
||||
mvc:
|
||||
contentnegotiation:
|
||||
favor-path-extension: true
|
||||
pathmatch:
|
||||
use-registered-suffix-pattern: true
|
||||
----
|
||||
|
||||
As of Spring Framework 5.3, Spring MVC supports several implementation strategies for matching request paths to Controller handlers.
|
||||
It was previously only supporting the `AntPathMatcher` strategy, but it now also offers `PathPatternParser`.
|
||||
Spring Boot now provides a configuration property to choose and opt in the new strategy:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
mvc:
|
||||
pathmatch:
|
||||
matching-strategy: "path-pattern-parser"
|
||||
----
|
||||
|
||||
For more details on why you should consider this new implementation, please check out the
|
||||
https://spring.io/blog/2020/06/30/url-matching-with-pathpattern-in-spring-mvc[dedicated blog post].
|
||||
|
||||
NOTE: `PathPatternParser` is an optimized implementation but restricts usage of
|
||||
{spring-framework-docs}/web.html#mvc-ann-requestmapping-uri-templates[some path patterns variants]
|
||||
and is incompatible with suffix pattern matching (configprop:spring.mvc.pathmatch.use-suffix-pattern[deprecated],
|
||||
configprop:spring.mvc.pathmatch.use-registered-suffix-pattern[deprecated]) or mapping the `DispatcherServlet`
|
||||
with a Servlet prefix (configprop:spring.mvc.servlet.path[]).
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.binding-initializer]]
|
||||
==== ConfigurableWebBindingInitializer
|
||||
Spring MVC uses a `WebBindingInitializer` to initialize a `WebDataBinder` for a particular request.
|
||||
If you create your own `ConfigurableWebBindingInitializer` `@Bean`, Spring Boot automatically configures Spring MVC to use it.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.template-engines]]
|
||||
==== Template Engines
|
||||
As well as REST web services, you can also use Spring MVC to serve dynamic HTML content.
|
||||
Spring MVC supports a variety of templating technologies, including Thymeleaf, FreeMarker, and JSPs.
|
||||
Also, many other templating engines include their own Spring MVC integrations.
|
||||
|
||||
Spring Boot includes auto-configuration support for the following templating engines:
|
||||
|
||||
* https://freemarker.apache.org/docs/[FreeMarker]
|
||||
* https://docs.groovy-lang.org/docs/next/html/documentation/template-engines.html#_the_markuptemplateengine[Groovy]
|
||||
* https://www.thymeleaf.org[Thymeleaf]
|
||||
* https://mustache.github.io/[Mustache]
|
||||
|
||||
TIP: If possible, JSPs should be avoided.
|
||||
There are several <<features#features.developing-web-applications.embedded-container.jsp-limitations, known limitations>> when using them with embedded servlet containers.
|
||||
|
||||
When you use one of these templating engines with the default configuration, your templates are picked up automatically from `src/main/resources/templates`.
|
||||
|
||||
TIP: Depending on how you run your application, your IDE may order the classpath differently.
|
||||
Running your application in the IDE from its main method results in a different ordering than when you run your application by using Maven or Gradle or from its packaged jar.
|
||||
This can cause Spring Boot to fail to find the expected template.
|
||||
If you have this problem, you can reorder the classpath in the IDE to place the module's classes and resources first.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.error-handling]]
|
||||
==== Error Handling
|
||||
By default, Spring Boot provides an `/error` mapping that handles all errors in a sensible way, and it is registered as a "`global`" error page in the servlet container.
|
||||
For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message.
|
||||
For browser clients, there is a "`whitelabel`" error view that renders the same data in HTML format (to customize it, add a `View` that resolves to `error`).
|
||||
|
||||
There are a number of `server.error` properties that can be set if you want to customize the default error handling behavior.
|
||||
See the <<application-properties#application-properties.server, "`Server Properties`">> section of the Appendix.
|
||||
|
||||
To replace the default behavior completely, you can implement `ErrorController` and register a bean definition of that type or add a bean of type `ErrorAttributes` to use the existing mechanism but replace the contents.
|
||||
|
||||
TIP: The `BasicErrorController` can be used as a base class for a custom `ErrorController`.
|
||||
This is particularly useful if you want to add a handler for a new content type (the default is to handle `text/html` specifically and provide a fallback for everything else).
|
||||
To do so, extend `BasicErrorController`, add a public method with a `@RequestMapping` that has a `produces` attribute, and create a bean of your new type.
|
||||
|
||||
You can also define a class annotated with `@ControllerAdvice` to customize the JSON document to return for a particular controller and/or exception type, as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/servlet/MyControllerAdvice.java[]
|
||||
----
|
||||
|
||||
In the preceding example, if `YourException` is thrown by a controller defined in the same package as `AcmeController`, a JSON representation of the `CustomErrorType` POJO is used instead of the `ErrorAttributes` representation.
|
||||
|
||||
In some cases, errors handled at the controller level are not recorded by the <<actuator#actuator.metrics.supported.spring-mvc, metrics infrastructure>>.
|
||||
Applications can ensure that such exceptions are recorded with the request metrics by setting the handled exception as a request attribute:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/servlet/MyController.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.error-handling.error-pages]]
|
||||
===== Custom Error Pages
|
||||
If you want to display a custom HTML error page for a given status code, you can add a file to an `/error` directory.
|
||||
Error pages can either be static HTML (that is, added under any of the static resource directories) or be built by using templates.
|
||||
The name of the file should be the exact status code or a series mask.
|
||||
|
||||
For example, to map `404` to a static HTML file, your directory structure would be as follows:
|
||||
|
||||
[source,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
src/
|
||||
+- main/
|
||||
+- java/
|
||||
| + <source code>
|
||||
+- resources/
|
||||
+- public/
|
||||
+- error/
|
||||
| +- 404.html
|
||||
+- <other public assets>
|
||||
----
|
||||
|
||||
To map all `5xx` errors by using a FreeMarker template, your directory structure would be as follows:
|
||||
|
||||
[source,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
src/
|
||||
+- main/
|
||||
+- java/
|
||||
| + <source code>
|
||||
+- resources/
|
||||
+- templates/
|
||||
+- error/
|
||||
| +- 5xx.ftlh
|
||||
+- <other templates>
|
||||
----
|
||||
|
||||
For more complex mappings, you can also add beans that implement the `ErrorViewResolver` interface, as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/servlet/MyErrorViewResolver.java[]
|
||||
----
|
||||
|
||||
You can also use regular Spring MVC features such as {spring-framework-docs}/web.html#mvc-exceptionhandlers[`@ExceptionHandler` methods] and {spring-framework-docs}/web.html#mvc-ann-controller-advice[`@ControllerAdvice`].
|
||||
The `ErrorController` then picks up any unhandled exceptions.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.error-handling.error-pages-without-spring-mvc]]
|
||||
===== Mapping Error Pages outside of Spring MVC
|
||||
For applications that do not use Spring MVC, you can use the `ErrorPageRegistrar` interface to directly register `ErrorPages`.
|
||||
This abstraction works directly with the underlying embedded servlet container and works even if you do not have a Spring MVC `DispatcherServlet`.
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/servlet/ErrorPageConfiguration.java[]
|
||||
----
|
||||
|
||||
NOTE: If you register an `ErrorPage` with a path that ends up being handled by a `Filter` (as is common with some non-Spring web frameworks, like Jersey and Wicket), then the `Filter` has to be explicitly registered as an `ERROR` dispatcher, as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/servlet/ServletFilterConfiguration.java[]
|
||||
----
|
||||
|
||||
Note that the default `FilterRegistrationBean` does not include the `ERROR` dispatcher type.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.error-handling.in-a-war-deployment]]
|
||||
===== Error handling in a war deployment
|
||||
When deployed to a servlet container, Spring Boot uses its error page filter to forward a request with an error status to the appropriate error page.
|
||||
This is necessary as the Servlet specification does not provide an API for registering error pages.
|
||||
Depending on the container that you are deploying your war file to and the technologies that your application uses, some additional configuration may be required.
|
||||
|
||||
The error page filter can only forward the request to the correct error page if the response has not already been committed.
|
||||
By default, WebSphere Application Server 8.0 and later commits the response upon successful completion of a servlet's service method.
|
||||
You should disable this behavior by setting `com.ibm.ws.webcontainer.invokeFlushAfterService` to `false`.
|
||||
|
||||
If you are using Spring Security and want to access the principal in an error page, you must configure Spring Security's filter to be invoked on error dispatches.
|
||||
To do so, set the `spring.security.filter.dispatcher-types` property to `async, error, forward, request`.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.spring-hateoas]]
|
||||
==== Spring HATEOAS
|
||||
If you develop a RESTful API that makes use of hypermedia, Spring Boot provides auto-configuration for Spring HATEOAS that works well with most applications.
|
||||
The auto-configuration replaces the need to use `@EnableHypermediaSupport` and registers a number of beans to ease building hypermedia-based applications, including a `LinkDiscoverers` (for client side support) and an `ObjectMapper` configured to correctly marshal responses into the desired representation.
|
||||
The `ObjectMapper` is customized by setting the various `spring.jackson.*` properties or, if one exists, by a `Jackson2ObjectMapperBuilder` bean.
|
||||
|
||||
You can take control of Spring HATEOAS's configuration by using `@EnableHypermediaSupport`.
|
||||
Note that doing so disables the `ObjectMapper` customization described earlier.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-mvc.cors]]
|
||||
==== CORS Support
|
||||
https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing] (CORS) is a https://www.w3.org/TR/cors/[W3C specification] implemented by https://caniuse.com/#feat=cors[most browsers] that lets you specify in a flexible way what kind of cross-domain requests are authorized., instead of using some less secure and less powerful approaches such as IFRAME or JSONP.
|
||||
|
||||
As of version 4.2, Spring MVC {spring-framework-docs}/web.html#mvc-cors[supports CORS].
|
||||
Using {spring-framework-docs}/web.html#mvc-cors-controller[controller method CORS configuration] with {spring-framework-api}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] annotations in your Spring Boot application does not require any specific configuration.
|
||||
{spring-framework-docs}/web.html#mvc-cors-global[Global CORS configuration] can be defined by registering a `WebMvcConfigurer` bean with a customized `addCorsMappings(CorsRegistry)` method, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/servlet/CorsConfiguration.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux]]
|
||||
=== The "`Spring WebFlux Framework`"
|
||||
Spring WebFlux is the new reactive web framework introduced in Spring Framework 5.0.
|
||||
Unlike Spring MVC, it does not require the Servlet API, is fully asynchronous and non-blocking, and implements the https://www.reactive-streams.org/[Reactive Streams] specification through https://projectreactor.io/[the Reactor project].
|
||||
|
||||
Spring WebFlux comes in two flavors: functional and annotation-based.
|
||||
The annotation-based one is quite close to the Spring MVC model, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/webflux/MyRestController.java[]
|
||||
----
|
||||
|
||||
"`WebFlux.fn`", the functional variant, separates the routing configuration from the actual handling of the requests, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/webflux/fn/RoutingConfiguration.java[]
|
||||
----
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/webflux/fn/UserHandler.java[]
|
||||
----
|
||||
|
||||
WebFlux is part of the Spring Framework and detailed information is available in its {spring-framework-docs}/web-reactive.html#webflux-fn[reference documentation].
|
||||
|
||||
TIP: You can define as many `RouterFunction` beans as you like to modularize the definition of the router.
|
||||
Beans can be ordered if you need to apply a precedence.
|
||||
|
||||
To get started, add the `spring-boot-starter-webflux` module to your application.
|
||||
|
||||
NOTE: Adding both `spring-boot-starter-web` and `spring-boot-starter-webflux` modules in your application results in Spring Boot auto-configuring Spring MVC, not WebFlux.
|
||||
This behavior has been chosen because many Spring developers add `spring-boot-starter-webflux` to their Spring MVC application to use the reactive `WebClient`.
|
||||
You can still enforce your choice by setting the chosen application type to `SpringApplication.setWebApplicationType(WebApplicationType.REACTIVE)`.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux.auto-configuration]]
|
||||
==== Spring WebFlux Auto-configuration
|
||||
Spring Boot provides auto-configuration for Spring WebFlux that works well with most applications.
|
||||
|
||||
The auto-configuration adds the following features on top of Spring's defaults:
|
||||
|
||||
* Configuring codecs for `HttpMessageReader` and `HttpMessageWriter` instances (described <<features#features.developing-web-applications.spring-webflux.httpcodecs,later in this document>>).
|
||||
* Support for serving static resources, including support for WebJars (described <<features#features.developing-web-applications.spring-mvc.static-content,later in this document>>).
|
||||
|
||||
If you want to keep Spring Boot WebFlux features and you want to add additional {spring-framework-docs}/web-reactive.html#webflux-config[WebFlux configuration], you can add your own `@Configuration` class of type `WebFluxConfigurer` but *without* `@EnableWebFlux`.
|
||||
|
||||
If you want to take complete control of Spring WebFlux, you can add your own `@Configuration` annotated with `@EnableWebFlux`.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux.httpcodecs]]
|
||||
==== HTTP Codecs with HttpMessageReaders and HttpMessageWriters
|
||||
Spring WebFlux uses the `HttpMessageReader` and `HttpMessageWriter` interfaces to convert HTTP requests and responses.
|
||||
They are configured with `CodecConfigurer` to have sensible defaults by looking at the libraries available in your classpath.
|
||||
|
||||
Spring Boot provides dedicated configuration properties for codecs, `+spring.codec.*+`.
|
||||
It also applies further customization by using `CodecCustomizer` instances.
|
||||
For example, `+spring.jackson.*+` configuration keys are applied to the Jackson codec.
|
||||
|
||||
If you need to add or customize codecs, you can create a custom `CodecCustomizer` component, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/webflux/CodecConfiguration.java[]
|
||||
----
|
||||
|
||||
You can also leverage <<features#features.developing-web-applications.spring-mvc.json,Boot's custom JSON serializers and deserializers>>.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux.static-content]]
|
||||
==== Static Content
|
||||
By default, Spring Boot serves static content from a directory called `/static` (or `/public` or `/resources` or `/META-INF/resources`) in the classpath.
|
||||
It uses the `ResourceWebHandler` from Spring WebFlux so that you can modify that behavior by adding your own `WebFluxConfigurer` and overriding the `addResourceHandlers` method.
|
||||
|
||||
By default, resources are mapped on `+/**+`, but you can tune that by setting the configprop:spring.webflux.static-path-pattern[] property.
|
||||
For instance, relocating all resources to `/resources/**` can be achieved as follows:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
webflux:
|
||||
static-path-pattern: "/resources/**"
|
||||
----
|
||||
|
||||
You can also customize the static resource locations by using `spring.web.resources.static-locations`.
|
||||
Doing so replaces the default values with a list of directory locations.
|
||||
If you do so, the default welcome page detection switches to your custom locations.
|
||||
So, if there is an `index.html` in any of your locations on startup, it is the home page of the application.
|
||||
|
||||
In addition to the "`standard`" static resource locations listed earlier, a special case is made for https://www.webjars.org/[Webjars content].
|
||||
Any resources with a path in `+/webjars/**+` are served from jar files if they are packaged in the Webjars format.
|
||||
|
||||
TIP: Spring WebFlux applications do not strictly depend on the Servlet API, so they cannot be deployed as war files and do not use the `src/main/webapp` directory.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux.welcome-page]]
|
||||
==== Welcome Page
|
||||
Spring Boot supports both static and templated welcome pages.
|
||||
It first looks for an `index.html` file in the configured static content locations.
|
||||
If one is not found, it then looks for an `index` template.
|
||||
If either is found, it is automatically used as the welcome page of the application.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux.template-engines]]
|
||||
==== Template Engines
|
||||
As well as REST web services, you can also use Spring WebFlux to serve dynamic HTML content.
|
||||
Spring WebFlux supports a variety of templating technologies, including Thymeleaf, FreeMarker, and Mustache.
|
||||
|
||||
Spring Boot includes auto-configuration support for the following templating engines:
|
||||
|
||||
* https://freemarker.apache.org/docs/[FreeMarker]
|
||||
* https://www.thymeleaf.org[Thymeleaf]
|
||||
* https://mustache.github.io/[Mustache]
|
||||
|
||||
When you use one of these templating engines with the default configuration, your templates are picked up automatically from `src/main/resources/templates`.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux.error-handling]]
|
||||
==== Error Handling
|
||||
Spring Boot provides a `WebExceptionHandler` that handles all errors in a sensible way.
|
||||
Its position in the processing order is immediately before the handlers provided by WebFlux, which are considered last.
|
||||
For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message.
|
||||
For browser clients, there is a "`whitelabel`" error handler that renders the same data in HTML format.
|
||||
You can also provide your own HTML templates to display errors (see the <<features#features.developing-web-applications.spring-webflux.error-handling.error-pages,next section>>).
|
||||
|
||||
The first step to customizing this feature often involves using the existing mechanism but replacing or augmenting the error contents.
|
||||
For that, you can add a bean of type `ErrorAttributes`.
|
||||
|
||||
To change the error handling behavior, you can implement `ErrorWebExceptionHandler` and register a bean definition of that type.
|
||||
Because a `WebExceptionHandler` is quite low-level, Spring Boot also provides a convenient `AbstractErrorWebExceptionHandler` to let you handle errors in a WebFlux functional way, as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/webflux/CustomErrorWebExceptionHandler.java[]
|
||||
----
|
||||
|
||||
For a more complete picture, you can also subclass `DefaultErrorWebExceptionHandler` directly and override specific methods.
|
||||
|
||||
In some cases, errors handled at the controller or handler function level are not recorded by the <<actuator#actuator.metrics.supported.spring-webflux, metrics infrastructure>>.
|
||||
Applications can ensure that such exceptions are recorded with the request metrics by setting the handled exception as a request attribute:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/webflux/ExceptionHandlingController.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux.error-handling.error-pages]]
|
||||
===== Custom Error Pages
|
||||
If you want to display a custom HTML error page for a given status code, you can add a file to an `/error` directory.
|
||||
Error pages can either be static HTML (that is, added under any of the static resource directories) or built with templates.
|
||||
The name of the file should be the exact status code or a series mask.
|
||||
|
||||
For example, to map `404` to a static HTML file, your directory structure would be as follows:
|
||||
|
||||
[source,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
src/
|
||||
+- main/
|
||||
+- java/
|
||||
| + <source code>
|
||||
+- resources/
|
||||
+- public/
|
||||
+- error/
|
||||
| +- 404.html
|
||||
+- <other public assets>
|
||||
----
|
||||
|
||||
To map all `5xx` errors by using a Mustache template, your directory structure would be as follows:
|
||||
|
||||
[source,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
src/
|
||||
+- main/
|
||||
+- java/
|
||||
| + <source code>
|
||||
+- resources/
|
||||
+- templates/
|
||||
+- error/
|
||||
| +- 5xx.mustache
|
||||
+- <other templates>
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.spring-webflux.web-filters]]
|
||||
==== Web Filters
|
||||
Spring WebFlux provides a `WebFilter` interface that can be implemented to filter HTTP request-response exchanges.
|
||||
`WebFilter` beans found in the application context will be automatically used to filter each exchange.
|
||||
|
||||
Where the order of the filters is important they can implement `Ordered` or be annotated with `@Order`.
|
||||
Spring Boot auto-configuration may configure web filters for you.
|
||||
When it does so, the orders shown in the following table will be used:
|
||||
|
||||
|===
|
||||
| Web Filter | Order
|
||||
|
||||
| `MetricsWebFilter`
|
||||
| `Ordered.HIGHEST_PRECEDENCE + 1`
|
||||
|
||||
| `WebFilterChainProxy` (Spring Security)
|
||||
| `-100`
|
||||
|
||||
| `HttpTraceWebFilter`
|
||||
| `Ordered.LOWEST_PRECEDENCE - 10`
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.jersey]]
|
||||
=== JAX-RS and Jersey
|
||||
If you prefer the JAX-RS programming model for REST endpoints, you can use one of the available implementations instead of Spring MVC.
|
||||
https://jersey.github.io/[Jersey] and https://cxf.apache.org/[Apache CXF] work quite well out of the box.
|
||||
CXF requires you to register its `Servlet` or `Filter` as a `@Bean` in your application context.
|
||||
Jersey has some native Spring support, so we also provide auto-configuration support for it in Spring Boot, together with a starter.
|
||||
|
||||
To get started with Jersey, include the `spring-boot-starter-jersey` as a dependency and then you need one `@Bean` of type `ResourceConfig` in which you register all the endpoints, as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/jersey/JerseyConfig.java[]
|
||||
----
|
||||
|
||||
WARNING: Jersey's support for scanning executable archives is rather limited.
|
||||
For example, it cannot scan for endpoints in a package found in a <<deployment#deployment.installing, fully executable jar file>> or in `WEB-INF/classes` when running an executable war file.
|
||||
To avoid this limitation, the `packages` method should not be used, and endpoints should be registered individually by using the `register` method, as shown in the preceding example.
|
||||
|
||||
For more advanced customizations, you can also register an arbitrary number of beans that implement `ResourceConfigCustomizer`.
|
||||
|
||||
All the registered endpoints should be `@Components` with HTTP resource annotations (`@GET` and others), as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/jersey/Endpoint.java[]
|
||||
----
|
||||
|
||||
Since the `Endpoint` is a Spring `@Component`, its lifecycle is managed by Spring and you can use the `@Autowired` annotation to inject dependencies and use the `@Value` annotation to inject external configuration.
|
||||
By default, the Jersey servlet is registered and mapped to `/*`.
|
||||
You can change the mapping by adding `@ApplicationPath` to your `ResourceConfig`.
|
||||
|
||||
By default, Jersey is set up as a Servlet in a `@Bean` of type `ServletRegistrationBean` named `jerseyServletRegistration`.
|
||||
By default, the servlet is initialized lazily, but you can customize that behavior by setting `spring.jersey.servlet.load-on-startup`.
|
||||
You can disable or override that bean by creating one of your own with the same name.
|
||||
You can also use a filter instead of a servlet by setting `spring.jersey.type=filter` (in which case, the `@Bean` to replace or override is `jerseyFilterRegistration`).
|
||||
The filter has an `@Order`, which you can set with `spring.jersey.filter.order`.
|
||||
Both the servlet and the filter registrations can be given init parameters by using `spring.jersey.init.*` to specify a map of properties.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container]]
|
||||
=== Embedded Servlet Container Support
|
||||
Spring Boot includes support for embedded https://tomcat.apache.org/[Tomcat], https://www.eclipse.org/jetty/[Jetty], and https://github.com/undertow-io/undertow[Undertow] servers.
|
||||
Most developers use the appropriate "`Starter`" to obtain a fully configured instance.
|
||||
By default, the embedded server listens for HTTP requests on port `8080`.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.servlets-filters-listeners]]
|
||||
==== Servlets, Filters, and listeners
|
||||
When using an embedded servlet container, you can register servlets, filters, and all the listeners (such as `HttpSessionListener`) from the Servlet spec, either by using Spring beans or by scanning for Servlet components.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.servlets-filters-listeners.beans]]
|
||||
===== Registering Servlets, Filters, and Listeners as Spring Beans
|
||||
Any `Servlet`, `Filter`, or servlet `*Listener` instance that is a Spring bean is registered with the embedded container.
|
||||
This can be particularly convenient if you want to refer to a value from your `application.properties` during configuration.
|
||||
|
||||
By default, if the context contains only a single Servlet, it is mapped to `/`.
|
||||
In the case of multiple servlet beans, the bean name is used as a path prefix.
|
||||
Filters map to `+/*+`.
|
||||
|
||||
If convention-based mapping is not flexible enough, you can use the `ServletRegistrationBean`, `FilterRegistrationBean`, and `ServletListenerRegistrationBean` classes for complete control.
|
||||
|
||||
It is usually safe to leave Filter beans unordered.
|
||||
If a specific order is required, you should annotate the `Filter` with `@Order` or make it implement `Ordered`.
|
||||
You cannot configure the order of a `Filter` by annotating its bean method with `@Order`.
|
||||
If you cannot change the `Filter` class to add `@Order` or implement `Ordered`, you must define a `FilterRegistrationBean` for the `Filter` and set the registration bean's order using the `setOrder(int)` method.
|
||||
Avoid configuring a Filter that reads the request body at `Ordered.HIGHEST_PRECEDENCE`, since it might go against the character encoding configuration of your application.
|
||||
If a Servlet filter wraps the request, it should be configured with an order that is less than or equal to `OrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDER`.
|
||||
|
||||
TIP: To see the order of every `Filter` in your application, enable debug level logging for the `web` <<features#features.logging.log-groups,logging group>> (`logging.level.web=debug`).
|
||||
Details of the registered filters, including their order and URL patterns, will then be logged at startup.
|
||||
|
||||
WARNING: Take care when registering `Filter` beans since they are initialized very early in the application lifecycle.
|
||||
If you need to register a `Filter` that interacts with other beans, consider using a {spring-boot-module-api}/web/servlet/DelegatingFilterProxyRegistrationBean.html[`DelegatingFilterProxyRegistrationBean`] instead.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.context-initializer]]
|
||||
==== Servlet Context Initialization
|
||||
Embedded servlet containers do not directly execute the Servlet 3.0+ `javax.servlet.ServletContainerInitializer` interface or Spring's `org.springframework.web.WebApplicationInitializer` interface.
|
||||
This is an intentional design decision intended to reduce the risk that third party libraries designed to run inside a war may break Spring Boot applications.
|
||||
|
||||
If you need to perform servlet context initialization in a Spring Boot application, you should register a bean that implements the `org.springframework.boot.web.servlet.ServletContextInitializer` interface.
|
||||
The single `onStartup` method provides access to the `ServletContext` and, if necessary, can easily be used as an adapter to an existing `WebApplicationInitializer`.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.context-initializer.scanning]]
|
||||
===== Scanning for Servlets, Filters, and listeners
|
||||
When using an embedded container, automatic registration of classes annotated with `@WebServlet`, `@WebFilter`, and `@WebListener` can be enabled by using `@ServletComponentScan`.
|
||||
|
||||
TIP: `@ServletComponentScan` has no effect in a standalone container, where the container's built-in discovery mechanisms are used instead.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.application-context]]
|
||||
==== The ServletWebServerApplicationContext
|
||||
Under the hood, Spring Boot uses a different type of `ApplicationContext` for embedded servlet container support.
|
||||
The `ServletWebServerApplicationContext` is a special type of `WebApplicationContext` that bootstraps itself by searching for a single `ServletWebServerFactory` bean.
|
||||
Usually a `TomcatServletWebServerFactory`, `JettyServletWebServerFactory`, or `UndertowServletWebServerFactory` has been auto-configured.
|
||||
|
||||
NOTE: You usually do not need to be aware of these implementation classes.
|
||||
Most applications are auto-configured, and the appropriate `ApplicationContext` and `ServletWebServerFactory` are created on your behalf.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.customizing]]
|
||||
==== Customizing Embedded Servlet Containers
|
||||
Common servlet container settings can be configured by using Spring `Environment` properties.
|
||||
Usually, you would define the properties in your `application.properties` or `application.yaml` file.
|
||||
|
||||
Common server settings include:
|
||||
|
||||
* Network settings: Listen port for incoming HTTP requests (`server.port`), interface address to bind to `server.address`, and so on.
|
||||
* Session settings: Whether the session is persistent (`server.servlet.session.persistent`), session timeout (`server.servlet.session.timeout`), location of session data (`server.servlet.session.store-dir`), and session-cookie configuration (`server.servlet.session.cookie.*`).
|
||||
* Error management: Location of the error page (`server.error.path`) and so on.
|
||||
* <<howto#howto.webserver.configure-ssl,SSL>>
|
||||
* <<howto#howto.webserver.enable-response-compression,HTTP compression>>
|
||||
|
||||
Spring Boot tries as much as possible to expose common settings, but this is not always possible.
|
||||
For those cases, dedicated namespaces offer server-specific customizations (see `server.tomcat` and `server.undertow`).
|
||||
For instance, <<howto#howto.webserver.configure-access-logs,access logs>> can be configured with specific features of the embedded servlet container.
|
||||
|
||||
TIP: See the {spring-boot-autoconfigure-module-code}/web/ServerProperties.java[`ServerProperties`] class for a complete list.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.customizing.programmatic]]
|
||||
===== Programmatic Customization
|
||||
If you need to programmatically configure your embedded servlet container, you can register a Spring bean that implements the `WebServerFactoryCustomizer` interface.
|
||||
`WebServerFactoryCustomizer` provides access to the `ConfigurableServletWebServerFactory`, which includes numerous customization setter methods.
|
||||
The following example shows programmatically setting the port:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/embeddedservletcontainer/CustomizationBean.java[]
|
||||
----
|
||||
|
||||
`TomcatServletWebServerFactory`, `JettyServletWebServerFactory` and `UndertowServletWebServerFactory` are dedicated variants of `ConfigurableServletWebServerFactory` that have additional customization setter methods for Tomcat, Jetty and Undertow respectively.
|
||||
The following example shows how to customize `TomcatServletWebServerFactory` that provides access to Tomcat-specific configuration options:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
include::{include-springbootfeatures}/webapplications/embeddedservletcontainer/TomcatServerCustomizer.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.customizing.direct]]
|
||||
===== Customizing ConfigurableServletWebServerFactory Directly
|
||||
For more advanced use cases that require you to extend from `ServletWebServerFactory`, you can expose a bean of such type yourself.
|
||||
|
||||
Setters are provided for many configuration options.
|
||||
Several protected method "`hooks`" are also provided should you need to do something more exotic.
|
||||
See the {spring-boot-module-api}/web/servlet/server/ConfigurableServletWebServerFactory.html[source code documentation] for details.
|
||||
|
||||
NOTE: Auto-configured customizers are still applied on your custom factory, so use that option carefully.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.embedded-container.jsp-limitations]]
|
||||
==== JSP Limitations
|
||||
When running a Spring Boot application that uses an embedded servlet container (and is packaged as an executable archive), there are some limitations in the JSP support.
|
||||
|
||||
* With Jetty and Tomcat, it should work if you use war packaging.
|
||||
An executable war will work when launched with `java -jar`, and will also be deployable to any standard container.
|
||||
JSPs are not supported when using an executable jar.
|
||||
|
||||
* Undertow does not support JSPs.
|
||||
|
||||
* Creating a custom `error.jsp` page does not override the default view for <<features#features.developing-web-applications.spring-mvc.error-handling,error handling>>.
|
||||
<<features#features.developing-web-applications.spring-mvc.error-handling.error-pages,Custom error pages>> should be used instead.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.reactive-server]]
|
||||
=== Embedded Reactive Server Support
|
||||
Spring Boot includes support for the following embedded reactive web servers: Reactor Netty, Tomcat, Jetty, and Undertow.
|
||||
Most developers use the appropriate “Starter” to obtain a fully configured instance.
|
||||
By default, the embedded server listens for HTTP requests on port 8080.
|
||||
|
||||
|
||||
|
||||
[[features.developing-web-applications.reactive-server-resources-configuration]]
|
||||
=== Reactive Server Resources Configuration
|
||||
When auto-configuring a Reactor Netty or Jetty server, Spring Boot will create specific beans that will provide HTTP resources to the server instance: `ReactorResourceFactory` or `JettyResourceFactory`.
|
||||
|
||||
By default, those resources will be also shared with the Reactor Netty and Jetty clients for optimal performances, given:
|
||||
|
||||
* the same technology is used for server and client
|
||||
* the client instance is built using the `WebClient.Builder` bean auto-configured by Spring Boot
|
||||
|
||||
Developers can override the resource configuration for Jetty and Reactor Netty by providing a custom `ReactorResourceFactory` or `JettyResourceFactory` bean - this will be applied to both clients and servers.
|
||||
|
||||
You can learn more about the resource configuration on the client side in the <<features#features.webclient.runtime, WebClient Runtime section>>.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
[[features.email]]
|
||||
== Sending Email
|
||||
The Spring Framework provides an abstraction for sending email by using the `JavaMailSender` interface, and Spring Boot provides auto-configuration for it as well as a starter module.
|
||||
|
||||
TIP: See the {spring-framework-docs}/integration.html#mail[reference documentation] for a detailed explanation of how you can use `JavaMailSender`.
|
||||
|
||||
If `spring.mail.host` and the relevant libraries (as defined by `spring-boot-starter-mail`) are available, a default `JavaMailSender` is created if none exists.
|
||||
The sender can be further customized by configuration items from the `spring.mail` namespace.
|
||||
See {spring-boot-autoconfigure-module-code}/mail/MailProperties.java[`MailProperties`] for more details.
|
||||
|
||||
In particular, certain default timeout values are infinite, and you may want to change that to avoid having a thread blocked by an unresponsive mail server, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
mail:
|
||||
properties:
|
||||
"[mail.smtp.connectiontimeout]": 5000
|
||||
"[mail.smtp.timeout]": 3000
|
||||
"[mail.smtp.writetimeout]": 5000
|
||||
----
|
||||
|
||||
It is also possible to configure a `JavaMailSender` with an existing `Session` from JNDI:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
mail:
|
||||
jndi-name: "mail/Session"
|
||||
----
|
||||
|
||||
When a `jndi-name` is set, it takes precedence over all other Session-related settings.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,30 @@
|
|||
[[features.graceful-shutdown]]
|
||||
== Graceful shutdown
|
||||
Graceful shutdown is supported with all four embedded web servers (Jetty, Reactor Netty, Tomcat, and Undertow) and with both reactive and Servlet-based web applications.
|
||||
It occurs as part of closing the application context and is performed in the earliest phase of stopping `SmartLifecycle` beans.
|
||||
This stop processing uses a timeout which provides a grace period during which existing requests will be allowed to complete but no new requests will be permitted.
|
||||
The exact way in which new requests are not permitted varies depending on the web server that is being used.
|
||||
Jetty, Reactor Netty, and Tomcat will stop accepting requests at the network layer.
|
||||
Undertow will accept requests but respond immediately with a service unavailable (503) response.
|
||||
|
||||
NOTE: Graceful shutdown with Tomcat requires Tomcat 9.0.33 or later.
|
||||
|
||||
To enable graceful shutdown, configure the configprop:server.shutdown[] property, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
server:
|
||||
shutdown: "graceful"
|
||||
----
|
||||
|
||||
To configure the timeout period, configure the configprop:spring.lifecycle.timeout-per-shutdown-phase[] property, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
lifecycle:
|
||||
timeout-per-shutdown-phase: "20s"
|
||||
----
|
||||
|
||||
IMPORTANT: Using graceful shutdown with your IDE may not work properly if it does not send a proper `SIGTERM` signal.
|
||||
Refer to the documentation of your IDE for more details.
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
[[features.hazelcast]]
|
||||
== Hazelcast
|
||||
If https://hazelcast.com/[Hazelcast] is on the classpath and a suitable configuration is found, Spring Boot auto-configures a `HazelcastInstance` that you can inject in your application.
|
||||
|
||||
Spring Boot first attempts to create a client by checking the following configuration options:
|
||||
|
||||
* The presence of a `com.hazelcast.client.config.ClientConfig` bean.
|
||||
* A configuration file defined by the configprop:spring.hazelcast.config[] property.
|
||||
* The presence of the `hazelcast.client.config` system property.
|
||||
* A `hazelcast-client.xml` in the working directory or at the root of the classpath.
|
||||
* A `hazelcast-client.yaml` in the working directory or at the root of the classpath.
|
||||
|
||||
NOTE: Spring Boot supports both Hazelcast 4 and Hazelcast 3.
|
||||
If you downgrade to Hazelcast 3, `hazelcast-client` should be added to the classpath to configure a client.
|
||||
|
||||
If a client can't be created, Spring Boot attempts to configure an embedded server.
|
||||
If you define a `com.hazelcast.config.Config` bean, Spring Boot uses that.
|
||||
If your configuration defines an instance name, Spring Boot tries to locate an existing instance rather than creating a new one.
|
||||
|
||||
You could also specify the Hazelcast configuration file to use through configuration, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
hazelcast:
|
||||
config: "classpath:config/my-hazelcast.xml"
|
||||
----
|
||||
|
||||
Otherwise, Spring Boot tries to find the Hazelcast configuration from the default locations: `hazelcast.xml` in the working directory or at the root of the classpath, or a `.yaml` counterpart in the same locations.
|
||||
We also check if the `hazelcast.config` system property is set.
|
||||
See the https://docs.hazelcast.org/docs/latest/manual/html-single/[Hazelcast documentation] for more details.
|
||||
|
||||
NOTE: Spring Boot also has <<features#features.caching.provider.hazelcast,explicit caching support for Hazelcast>>.
|
||||
If caching is enabled, the `HazelcastInstance` is automatically wrapped in a `CacheManager` implementation.
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
[[features.internationalization]]
|
||||
== Internationalization
|
||||
Spring Boot supports localized messages so that your application can cater to users of different language preferences.
|
||||
By default, Spring Boot looks for the presence of a `messages` resource bundle at the root of the classpath.
|
||||
|
||||
NOTE: The auto-configuration applies when the default properties file for the configured resource bundle is available (i.e. `messages.properties` by default).
|
||||
If your resource bundle contains only language-specific properties files, you are required to add the default.
|
||||
If no properties file is found that matches any of the configured base names, there will be no auto-configured `MessageSource`.
|
||||
|
||||
The basename of the resource bundle as well as several other attributes can be configured using the `spring.messages` namespace, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
messages:
|
||||
basename: "messages,config.i18n.messages"
|
||||
fallback-to-system-locale: false
|
||||
----
|
||||
|
||||
TIP: `spring.messages.basename` supports comma-separated list of locations, either a package qualifier or a resource resolved from the classpath root.
|
||||
|
||||
See {spring-boot-autoconfigure-module-code}/context/MessageSourceProperties.java[`MessageSourceProperties`] for more supported options.
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
[[features.jmx]]
|
||||
== Monitoring and Management over JMX
|
||||
Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications.
|
||||
Spring Boot exposes the most suitable `MBeanServer` as a bean with an ID of `mbeanServer`.
|
||||
Any of your beans that are annotated with Spring JMX annotations (`@ManagedResource`, `@ManagedAttribute`, or `@ManagedOperation`) are exposed to it.
|
||||
|
||||
If your platform provides a standard `MBeanServer`, Spring Boot will use that and default to the VM `MBeanServer` if necessary.
|
||||
If all that fails, a new `MBeanServer` will be created.
|
||||
|
||||
See the {spring-boot-autoconfigure-module-code}/jmx/JmxAutoConfiguration.java[`JmxAutoConfiguration`] class for more details.
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
[[features.json]]
|
||||
== JSON
|
||||
Spring Boot provides integration with three JSON mapping libraries:
|
||||
|
||||
- Gson
|
||||
- Jackson
|
||||
- JSON-B
|
||||
|
||||
Jackson is the preferred and default library.
|
||||
|
||||
|
||||
|
||||
[[features.json.jackson]]
|
||||
=== Jackson
|
||||
Auto-configuration for Jackson is provided and Jackson is part of `spring-boot-starter-json`.
|
||||
When Jackson is on the classpath an `ObjectMapper` bean is automatically configured.
|
||||
Several configuration properties are provided for <<howto#howto.spring-mvc.customize-jackson-objectmapper,customizing the configuration of the `ObjectMapper`>>.
|
||||
|
||||
|
||||
|
||||
[[features.json.gson]]
|
||||
=== Gson
|
||||
Auto-configuration for Gson is provided.
|
||||
When Gson is on the classpath a `Gson` bean is automatically configured.
|
||||
Several `+spring.gson.*+` configuration properties are provided for customizing the configuration.
|
||||
To take more control, one or more `GsonBuilderCustomizer` beans can be used.
|
||||
|
||||
|
||||
|
||||
[[features.json.json-b]]
|
||||
=== JSON-B
|
||||
Auto-configuration for JSON-B is provided.
|
||||
When the JSON-B API and an implementation are on the classpath a `Jsonb` bean will be automatically configured.
|
||||
The preferred JSON-B implementation is Apache Johnzon for which dependency management is provided.
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
[[features.jta]]
|
||||
== Distributed Transactions with JTA
|
||||
Spring Boot supports distributed JTA transactions across multiple XA resources by using an https://www.atomikos.com/[Atomikos] embedded transaction manager.
|
||||
JTA transactions are also supported when deploying to a suitable Java EE Application Server.
|
||||
|
||||
When a JTA environment is detected, Spring's `JtaTransactionManager` is used to manage transactions.
|
||||
Auto-configured JMS, DataSource, and JPA beans are upgraded to support XA transactions.
|
||||
You can use standard Spring idioms, such as `@Transactional`, to participate in a distributed transaction.
|
||||
If you are within a JTA environment and still want to use local transactions, you can set the configprop:spring.jta.enabled[] property to `false` to disable the JTA auto-configuration.
|
||||
|
||||
|
||||
|
||||
[[features.jta.atomikos]]
|
||||
=== Using an Atomikos Transaction Manager
|
||||
https://www.atomikos.com/[Atomikos] is a popular open source transaction manager which can be embedded into your Spring Boot application.
|
||||
You can use the `spring-boot-starter-jta-atomikos` starter to pull in the appropriate Atomikos libraries.
|
||||
Spring Boot auto-configures Atomikos and ensures that appropriate `depends-on` settings are applied to your Spring beans for correct startup and shutdown ordering.
|
||||
|
||||
By default, Atomikos transaction logs are written to a `transaction-logs` directory in your application's home directory (the directory in which your application jar file resides).
|
||||
You can customize the location of this directory by setting a configprop:spring.jta.log-dir[] property in your `application.properties` file.
|
||||
Properties starting with `spring.jta.atomikos.properties` can also be used to customize the Atomikos `UserTransactionServiceImp`.
|
||||
See the {spring-boot-module-api}/jta/atomikos/AtomikosProperties.html[`AtomikosProperties` Javadoc] for complete details.
|
||||
|
||||
NOTE: To ensure that multiple transaction managers can safely coordinate the same resource managers, each Atomikos instance must be configured with a unique ID.
|
||||
By default, this ID is the IP address of the machine on which Atomikos is running.
|
||||
To ensure uniqueness in production, you should configure the configprop:spring.jta.transaction-manager-id[] property with a different value for each instance of your application.
|
||||
|
||||
|
||||
|
||||
[[features.jta.javaee]]
|
||||
=== Using a Java EE Managed Transaction Manager
|
||||
If you package your Spring Boot application as a `war` or `ear` file and deploy it to a Java EE application server, you can use your application server's built-in transaction manager.
|
||||
Spring Boot tries to auto-configure a transaction manager by looking at common JNDI locations (`java:comp/UserTransaction`, `java:comp/TransactionManager`, and so on).
|
||||
If you use a transaction service provided by your application server, you generally also want to ensure that all resources are managed by the server and exposed over JNDI.
|
||||
Spring Boot tries to auto-configure JMS by looking for a `ConnectionFactory` at the JNDI path (`java:/JmsXA` or `java:/XAConnectionFactory`), and you can use the <<features#features.sql.datasource.jndi, configprop:spring.datasource.jndi-name[] property>> to configure your `DataSource`.
|
||||
|
||||
|
||||
|
||||
[[features.jta.mixing-xa-and-non-xa-connections]]
|
||||
=== Mixing XA and Non-XA JMS Connections
|
||||
When using JTA, the primary JMS `ConnectionFactory` bean is XA-aware and participates in distributed transactions.
|
||||
You can inject into your bean without needing to use any `@Qualifier`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/jta/primary/MyBean.java[tag=*]
|
||||
----
|
||||
|
||||
In some situations, you might want to process certain JMS messages by using a non-XA `ConnectionFactory`.
|
||||
For example, your JMS processing logic might take longer than the XA timeout.
|
||||
|
||||
If you want to use a non-XA `ConnectionFactory`, you can the `nonXaJmsConnectionFactory` bean:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/jta/nonxa/MyBean.java[tag=*]
|
||||
----
|
||||
|
||||
For consistency, the `jmsConnectionFactory` bean is also provided by using the bean alias `xaJmsConnectionFactory`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/jta/xa/MyBean.java[tag=*]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.jta.supporting-alternative-embedded-transaction-manager]]
|
||||
=== Supporting an Alternative Embedded Transaction Manager
|
||||
The {spring-boot-module-code}/jms/XAConnectionFactoryWrapper.java[`XAConnectionFactoryWrapper`] and {spring-boot-module-code}/jdbc/XADataSourceWrapper.java[`XADataSourceWrapper`] interfaces can be used to support alternative embedded transaction managers.
|
||||
The interfaces are responsible for wrapping `XAConnectionFactory` and `XADataSource` beans and exposing them as regular `ConnectionFactory` and `DataSource` beans, which transparently enroll in the distributed transaction.
|
||||
DataSource and JMS auto-configuration use JTA variants, provided you have a `JtaTransactionManager` bean and appropriate XA wrapper beans registered within your `ApplicationContext`.
|
||||
|
||||
The {spring-boot-module-code}/jta/atomikos/AtomikosXAConnectionFactoryWrapper.java[AtomikosXAConnectionFactoryWrapper] and {spring-boot-module-code}/jta/atomikos/AtomikosXADataSourceWrapper.java[AtomikosXADataSourceWrapper] provide good examples of how to write XA wrappers.
|
||||
|
|
@ -0,0 +1,173 @@
|
|||
[[features.kotlin]]
|
||||
== Kotlin support
|
||||
https://kotlinlang.org[Kotlin] is a statically-typed language targeting the JVM (and other platforms) which allows writing concise and elegant code while providing {kotlin-docs}java-interop.html[interoperability] with existing libraries written in Java.
|
||||
|
||||
Spring Boot provides Kotlin support by leveraging the support in other Spring projects such as Spring Framework, Spring Data, and Reactor.
|
||||
See the {spring-framework-docs}/languages.html#kotlin[Spring Framework Kotlin support documentation] for more information.
|
||||
|
||||
The easiest way to start with Spring Boot and Kotlin is to follow https://spring.io/guides/tutorials/spring-boot-kotlin/[this comprehensive tutorial].
|
||||
You can create new Kotlin projects via https://start.spring.io/#!language=kotlin[start.spring.io].
|
||||
Feel free to join the #spring channel of https://slack.kotlinlang.org/[Kotlin Slack] or ask a question with the `spring` and `kotlin` tags on https://stackoverflow.com/questions/tagged/spring+kotlin[Stack Overflow] if you need support.
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.requirements]]
|
||||
=== Requirements
|
||||
Spring Boot supports Kotlin 1.3.x.
|
||||
To use Kotlin, `org.jetbrains.kotlin:kotlin-stdlib` and `org.jetbrains.kotlin:kotlin-reflect` must be present on the classpath.
|
||||
The `kotlin-stdlib` variants `kotlin-stdlib-jdk7` and `kotlin-stdlib-jdk8` can also be used.
|
||||
|
||||
Since https://discuss.kotlinlang.org/t/classes-final-by-default/166[Kotlin classes are final by default], you are likely to want to configure {kotlin-docs}compiler-plugins.html#spring-support[kotlin-spring] plugin in order to automatically open Spring-annotated classes so that they can be proxied.
|
||||
|
||||
https://github.com/FasterXML/jackson-module-kotlin[Jackson's Kotlin module] is required for serializing / deserializing JSON data in Kotlin.
|
||||
It is automatically registered when found on the classpath.
|
||||
A warning message is logged if Jackson and Kotlin are present but the Jackson Kotlin module is not.
|
||||
|
||||
TIP: These dependencies and plugins are provided by default if one bootstraps a Kotlin project on https://start.spring.io/#!language=kotlin[start.spring.io].
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.null-safety]]
|
||||
=== Null-safety
|
||||
One of Kotlin's key features is {kotlin-docs}null-safety.html[null-safety].
|
||||
It deals with `null` values at compile time rather than deferring the problem to runtime and encountering a `NullPointerException`.
|
||||
This helps to eliminate a common source of bugs without paying the cost of wrappers like `Optional`.
|
||||
Kotlin also allows using functional constructs with nullable values as described in this https://www.baeldung.com/kotlin-null-safety[comprehensive guide to null-safety in Kotlin].
|
||||
|
||||
Although Java does not allow one to express null-safety in its type system, Spring Framework, Spring Data, and Reactor now provide null-safety of their API via tooling-friendly annotations.
|
||||
By default, types from Java APIs used in Kotlin are recognized as {kotlin-docs}java-interop.html#null-safety-and-platform-types[platform types] for which null-checks are relaxed.
|
||||
{kotlin-docs}java-interop.html#jsr-305-support[Kotlin's support for JSR 305 annotations] combined with nullability annotations provide null-safety for the related Spring API in Kotlin.
|
||||
|
||||
The JSR 305 checks can be configured by adding the `-Xjsr305` compiler flag with the following options: `-Xjsr305={strict|warn|ignore}`.
|
||||
The default behavior is the same as `-Xjsr305=warn`.
|
||||
The `strict` value is required to have null-safety taken in account in Kotlin types inferred from Spring API but should be used with the knowledge that Spring API nullability declaration could evolve even between minor releases and more checks may be added in the future).
|
||||
|
||||
WARNING: Generic type arguments, varargs and array elements nullability are not yet supported.
|
||||
See https://jira.spring.io/browse/SPR-15942[SPR-15942] for up-to-date information.
|
||||
Also be aware that Spring Boot's own API is {github-issues}10712[not yet annotated].
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.api]]
|
||||
=== Kotlin API
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.api.?run-application]]
|
||||
==== runApplication
|
||||
Spring Boot provides an idiomatic way to run an application with `runApplication<MyApplication>(*args)` as shown in the following example:
|
||||
|
||||
[source,kotlin,indent=0]
|
||||
----
|
||||
import org.springframework.boot.autoconfigure.SpringBootApplication
|
||||
import org.springframework.boot.runApplication
|
||||
|
||||
@SpringBootApplication
|
||||
class MyApplication
|
||||
|
||||
fun main(args: Array<String>) {
|
||||
runApplication<MyApplication>(*args)
|
||||
}
|
||||
----
|
||||
|
||||
This is a drop-in replacement for `SpringApplication.run(MyApplication::class.java, *args)`.
|
||||
It also allows customization of the application as shown in the following example:
|
||||
|
||||
[source,kotlin,indent=0]
|
||||
----
|
||||
runApplication<MyApplication>(*args) {
|
||||
setBannerMode(OFF)
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.api.extensions]]
|
||||
==== Extensions
|
||||
Kotlin {kotlin-docs}extensions.html[extensions] provide the ability to extend existing classes with additional functionality.
|
||||
The Spring Boot Kotlin API makes use of these extensions to add new Kotlin specific conveniences to existing APIs.
|
||||
|
||||
`TestRestTemplate` extensions, similar to those provided by Spring Framework for `RestOperations` in Spring Framework, are provided.
|
||||
Among other things, the extensions make it possible to take advantage of Kotlin reified type parameters.
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.dependency-management]]
|
||||
=== Dependency management
|
||||
In order to avoid mixing different versions of Kotlin dependencies on the classpath, Spring Boot imports the Kotlin BOM.
|
||||
|
||||
With Maven, the Kotlin version can be customized via the `kotlin.version` property and plugin management is provided for `kotlin-maven-plugin`.
|
||||
With Gradle, the Spring Boot plugin automatically aligns the `kotlin.version` with the version of the Kotlin plugin.
|
||||
|
||||
Spring Boot also manages the version of Coroutines dependencies by importing the Kotlin Coroutines BOM.
|
||||
The version can be customized via the `kotlin-coroutines.version` property.
|
||||
|
||||
TIP: `org.jetbrains.kotlinx:kotlinx-coroutines-reactor` dependency is provided by default if one bootstraps a Kotlin project with at least one reactive dependency on https://start.spring.io/#!language=kotlin[start.spring.io].
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.configuration-properties]]
|
||||
=== @ConfigurationProperties
|
||||
`@ConfigurationProperties` when used in combination with <<features#features.external-config.typesafe-configuration-properties.constructor-binding,`@ConstructorBinding`>> supports classes with immutable `val` properties as shown in the following example:
|
||||
|
||||
[source,kotlin,indent=0]
|
||||
----
|
||||
@ConstructorBinding
|
||||
@ConfigurationProperties("example.kotlin")
|
||||
data class KotlinExampleProperties(
|
||||
val name: String,
|
||||
val description: String,
|
||||
val myService: MyService) {
|
||||
|
||||
data class MyService(
|
||||
val apiToken: String,
|
||||
val uri: URI
|
||||
)
|
||||
}
|
||||
----
|
||||
|
||||
TIP: To generate <<configuration-metadata#configuration-metadata.annotation-processor,your own metadata>> using the annotation processor, {kotlin-docs}kapt.html[`kapt` should be configured] with the `spring-boot-configuration-processor` dependency.
|
||||
Note that some features (such as detecting the default value or deprecated items) are not working due to limitations in the model kapt provides.
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.testing]]
|
||||
=== Testing
|
||||
While it is possible to use JUnit 4 to test Kotlin code, JUnit 5 is provided by default and is recommended.
|
||||
JUnit 5 enables a test class to be instantiated once and reused for all of the class's tests.
|
||||
This makes it possible to use `@BeforeAll` and `@AfterAll` annotations on non-static methods, which is a good fit for Kotlin.
|
||||
|
||||
To mock Kotlin classes, https://mockk.io/[MockK] is recommended.
|
||||
If you need the `Mockk` equivalent of the Mockito specific <<features#features.testing.spring-boot-applications.mocking-beans,`@MockBean` and `@SpyBean` annotations>>, you can use https://github.com/Ninja-Squad/springmockk[SpringMockK] which provides similar `@MockkBean` and `@SpykBean` annotations.
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.resources]]
|
||||
=== Resources
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.resources.further-reading]]
|
||||
==== Further reading
|
||||
* {kotlin-docs}[Kotlin language reference]
|
||||
* https://kotlinlang.slack.com/[Kotlin Slack] (with a dedicated #spring channel)
|
||||
* https://stackoverflow.com/questions/tagged/spring+kotlin[Stackoverflow with `spring` and `kotlin` tags]
|
||||
* https://try.kotlinlang.org/[Try Kotlin in your browser]
|
||||
* https://blog.jetbrains.com/kotlin/[Kotlin blog]
|
||||
* https://kotlin.link/[Awesome Kotlin]
|
||||
* https://spring.io/guides/tutorials/spring-boot-kotlin/[Tutorial: building web applications with Spring Boot and Kotlin]
|
||||
* https://spring.io/blog/2016/02/15/developing-spring-boot-applications-with-kotlin[Developing Spring Boot applications with Kotlin]
|
||||
* https://spring.io/blog/2016/03/20/a-geospatial-messenger-with-kotlin-spring-boot-and-postgresql[A Geospatial Messenger with Kotlin, Spring Boot and PostgreSQL]
|
||||
* https://spring.io/blog/2017/01/04/introducing-kotlin-support-in-spring-framework-5-0[Introducing Kotlin support in Spring Framework 5.0]
|
||||
* https://spring.io/blog/2017/08/01/spring-framework-5-kotlin-apis-the-functional-way[Spring Framework 5 Kotlin APIs, the functional way]
|
||||
|
||||
|
||||
|
||||
[[features.kotlin.resources.examples]]
|
||||
==== Examples
|
||||
* https://github.com/sdeleuze/spring-boot-kotlin-demo[spring-boot-kotlin-demo]: regular Spring Boot + Spring Data JPA project
|
||||
* https://github.com/mixitconf/mixit[mixit]: Spring Boot 2 + WebFlux + Reactive Spring Data MongoDB
|
||||
* https://github.com/sdeleuze/spring-kotlin-fullstack[spring-kotlin-fullstack]: WebFlux Kotlin fullstack example with Kotlin2js for frontend instead of JavaScript or TypeScript
|
||||
* https://github.com/spring-petclinic/spring-petclinic-kotlin[spring-petclinic-kotlin]: Kotlin version of the Spring PetClinic Sample Application
|
||||
* https://github.com/sdeleuze/spring-kotlin-deepdive[spring-kotlin-deepdive]: a step by step migration for Boot 1.0 + Java to Boot 2.0 + Kotlin
|
||||
* https://github.com/sdeleuze/spring-boot-coroutines-demo[spring-boot-coroutines-demo]: Coroutines sample project
|
||||
|
|
@ -0,0 +1,481 @@
|
|||
[[features.logging]]
|
||||
== Logging
|
||||
Spring Boot uses https://commons.apache.org/logging[Commons Logging] for all internal logging but leaves the underlying log implementation open.
|
||||
Default configurations are provided for {java-api}/java/util/logging/package-summary.html[Java Util Logging], https://logging.apache.org/log4j/2.x/[Log4J2], and https://logback.qos.ch/[Logback].
|
||||
In each case, loggers are pre-configured to use console output with optional file output also available.
|
||||
|
||||
By default, if you use the "`Starters`", Logback is used for logging.
|
||||
Appropriate Logback routing is also included to ensure that dependent libraries that use Java Util Logging, Commons Logging, Log4J, or SLF4J all work correctly.
|
||||
|
||||
TIP: There are a lot of logging frameworks available for Java.
|
||||
Do not worry if the above list seems confusing.
|
||||
Generally, you do not need to change your logging dependencies and the Spring Boot defaults work just fine.
|
||||
|
||||
TIP: When you deploy your application to a servlet container or application server, logging performed via the Java Util Logging API is not routed into your application's logs.
|
||||
This prevents logging performed by the container or other applications that have been deployed to it from appearing in your application's logs.
|
||||
|
||||
|
||||
|
||||
[[features.logging.log-format]]
|
||||
=== Log Format
|
||||
The default log output from Spring Boot resembles the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
2019-03-05 10:57:51.112 INFO 45469 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet Engine: Apache Tomcat/7.0.52
|
||||
2019-03-05 10:57:51.253 INFO 45469 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
|
||||
2019-03-05 10:57:51.253 INFO 45469 --- [ost-startStop-1] o.s.web.context.ContextLoader : Root WebApplicationContext: initialization completed in 1358 ms
|
||||
2019-03-05 10:57:51.698 INFO 45469 --- [ost-startStop-1] o.s.b.c.e.ServletRegistrationBean : Mapping servlet: 'dispatcherServlet' to [/]
|
||||
2019-03-05 10:57:51.702 INFO 45469 --- [ost-startStop-1] o.s.b.c.embedded.FilterRegistrationBean : Mapping filter: 'hiddenHttpMethodFilter' to: [/*]
|
||||
----
|
||||
|
||||
The following items are output:
|
||||
|
||||
* Date and Time: Millisecond precision and easily sortable.
|
||||
* Log Level: `ERROR`, `WARN`, `INFO`, `DEBUG`, or `TRACE`.
|
||||
* Process ID.
|
||||
* A `---` separator to distinguish the start of actual log messages.
|
||||
* Thread name: Enclosed in square brackets (may be truncated for console output).
|
||||
* Logger name: This is usually the source class name (often abbreviated).
|
||||
* The log message.
|
||||
|
||||
NOTE: Logback does not have a `FATAL` level.
|
||||
It is mapped to `ERROR`.
|
||||
|
||||
|
||||
|
||||
[[features.logging.console-output]]
|
||||
=== Console Output
|
||||
The default log configuration echoes messages to the console as they are written.
|
||||
By default, `ERROR`-level, `WARN`-level, and `INFO`-level messages are logged.
|
||||
You can also enable a "`debug`" mode by starting your application with a `--debug` flag.
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ java -jar myapp.jar --debug
|
||||
----
|
||||
|
||||
NOTE: You can also specify `debug=true` in your `application.properties`.
|
||||
|
||||
When the debug mode is enabled, a selection of core loggers (embedded container, Hibernate, and Spring Boot) are configured to output more information.
|
||||
Enabling the debug mode does _not_ configure your application to log all messages with `DEBUG` level.
|
||||
|
||||
Alternatively, you can enable a "`trace`" mode by starting your application with a `--trace` flag (or `trace=true` in your `application.properties`).
|
||||
Doing so enables trace logging for a selection of core loggers (embedded container, Hibernate schema generation, and the whole Spring portfolio).
|
||||
|
||||
|
||||
|
||||
[[features.logging.console-output.color-coded]]
|
||||
==== Color-coded Output
|
||||
If your terminal supports ANSI, color output is used to aid readability.
|
||||
You can set `spring.output.ansi.enabled` to a {spring-boot-module-api}/ansi/AnsiOutput.Enabled.html[supported value] to override the auto-detection.
|
||||
|
||||
Color coding is configured by using the `%clr` conversion word.
|
||||
In its simplest form, the converter colors the output according to the log level, as shown in the following example:
|
||||
|
||||
[source,indent=0]
|
||||
----
|
||||
%clr(%5p)
|
||||
----
|
||||
|
||||
The following table describes the mapping of log levels to colors:
|
||||
|
||||
|===
|
||||
| Level | Color
|
||||
|
||||
| `FATAL`
|
||||
| Red
|
||||
|
||||
| `ERROR`
|
||||
| Red
|
||||
|
||||
| `WARN`
|
||||
| Yellow
|
||||
|
||||
| `INFO`
|
||||
| Green
|
||||
|
||||
| `DEBUG`
|
||||
| Green
|
||||
|
||||
| `TRACE`
|
||||
| Green
|
||||
|===
|
||||
|
||||
Alternatively, you can specify the color or style that should be used by providing it as an option to the conversion.
|
||||
For example, to make the text yellow, use the following setting:
|
||||
|
||||
[source,indent=0]
|
||||
----
|
||||
%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){yellow}
|
||||
----
|
||||
|
||||
The following colors and styles are supported:
|
||||
|
||||
* `blue`
|
||||
* `cyan`
|
||||
* `faint`
|
||||
* `green`
|
||||
* `magenta`
|
||||
* `red`
|
||||
* `yellow`
|
||||
|
||||
|
||||
|
||||
[[features.logging.file-output]]
|
||||
=== File Output
|
||||
By default, Spring Boot logs only to the console and does not write log files.
|
||||
If you want to write log files in addition to the console output, you need to set a configprop:logging.file.name[] or configprop:logging.file.path[] property (for example, in your `application.properties`).
|
||||
|
||||
The following table shows how the `logging.*` properties can be used together:
|
||||
|
||||
.Logging properties
|
||||
[cols="1,1,1,4"]
|
||||
|===
|
||||
| configprop:logging.file.name[] | configprop:logging.file.path[] | Example | Description
|
||||
|
||||
| _(none)_
|
||||
| _(none)_
|
||||
|
|
||||
| Console only logging.
|
||||
|
||||
| Specific file
|
||||
| _(none)_
|
||||
| `my.log`
|
||||
| Writes to the specified log file.
|
||||
Names can be an exact location or relative to the current directory.
|
||||
|
||||
| _(none)_
|
||||
| Specific directory
|
||||
| `/var/log`
|
||||
| Writes `spring.log` to the specified directory.
|
||||
Names can be an exact location or relative to the current directory.
|
||||
|===
|
||||
|
||||
Log files rotate when they reach 10 MB and, as with console output, `ERROR`-level, `WARN`-level, and `INFO`-level messages are logged by default.
|
||||
|
||||
TIP: Logging properties are independent of the actual logging infrastructure.
|
||||
As a result, specific configuration keys (such as `logback.configurationFile` for Logback) are not managed by spring Boot.
|
||||
|
||||
|
||||
|
||||
[[features.logging.file-rotation]]
|
||||
=== File Rotation
|
||||
If you are using the Logback, it's possible to fine-tune log rotation settings using your `application.properties` or `application.yaml` file.
|
||||
For all other logging system, you'll need to configure rotation settings directly yourself (for example, if you use Log4J2 then you could add a `log4j.xml` file).
|
||||
|
||||
The following rotation policy properties are supported:
|
||||
|
||||
|===
|
||||
| Name | Description
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.file-name-pattern[]
|
||||
| The filename pattern used to create log archives.
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.clean-history-on-start[]
|
||||
| If log archive cleanup should occur when the application starts.
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.max-file-size[]
|
||||
| The maximum size of log file before it's archived.
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.total-size-cap[]
|
||||
| The maximum amount of size log archives can take before being deleted.
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.max-history[]
|
||||
| The number of days to keep log archives (defaults to 7)
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[features.logging.log-levels]]
|
||||
=== Log Levels
|
||||
All the supported logging systems can have the logger levels set in the Spring `Environment` (for example, in `application.properties`) by using `+logging.level.<logger-name>=<level>+` where `level` is one of TRACE, DEBUG, INFO, WARN, ERROR, FATAL, or OFF.
|
||||
The `root` logger can be configured by using `logging.level.root`.
|
||||
|
||||
The following example shows potential logging settings in `application.properties`:
|
||||
|
||||
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops,role="primary"]
|
||||
.Properties
|
||||
----
|
||||
logging.level.root=warn
|
||||
logging.level.org.springframework.web=debug
|
||||
logging.level.org.hibernate=error
|
||||
----
|
||||
|
||||
[source,properties,indent=0,subs="verbatim,quotes,attributes",role="secondary"]
|
||||
.Yaml
|
||||
----
|
||||
logging:
|
||||
level:
|
||||
root: "warn"
|
||||
org.springframework.web: "debug"
|
||||
org.hibernate: "error"
|
||||
----
|
||||
|
||||
It's also possible to set logging levels using environment variables.
|
||||
For example, `LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG` will set `org.springframework.web` to `DEBUG`.
|
||||
|
||||
NOTE: The above approach will only work for package level logging.
|
||||
Since relaxed binding always converts environment variables to lowercase, it's not possible to configure logging for an individual class in this way.
|
||||
If you need to configure logging for a class, you can use <<features#features.external-config.application-json, the `SPRING_APPLICATION_JSON`>> variable.
|
||||
|
||||
|
||||
|
||||
[[features.logging.log-groups]]
|
||||
=== Log Groups
|
||||
It's often useful to be able to group related loggers together so that they can all be configured at the same time.
|
||||
For example, you might commonly change the logging levels for _all_ Tomcat related loggers, but you can't easily remember top level packages.
|
||||
|
||||
To help with this, Spring Boot allows you to define logging groups in your Spring `Environment`.
|
||||
For example, here's how you could define a "`tomcat`" group by adding it to your `application.properties`:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
logging:
|
||||
group:
|
||||
tomcat: "org.apache.catalina,org.apache.coyote,org.apache.tomcat"
|
||||
----
|
||||
|
||||
Once defined, you can change the level for all the loggers in the group with a single line:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
logging:
|
||||
level:
|
||||
tomcat: "trace"
|
||||
----
|
||||
|
||||
Spring Boot includes the following pre-defined logging groups that can be used out-of-the-box:
|
||||
|
||||
[cols="1,4"]
|
||||
|===
|
||||
| Name | Loggers
|
||||
|
||||
| web
|
||||
| `org.springframework.core.codec`, `org.springframework.http`, `org.springframework.web`, `org.springframework.boot.actuate.endpoint.web`, `org.springframework.boot.web.servlet.ServletContextInitializerBeans`
|
||||
|
||||
| sql
|
||||
| `org.springframework.jdbc.core`, `org.hibernate.SQL`, `org.jooq.tools.LoggerListener`
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[features.logging.shutdown-hook]]
|
||||
=== Using a Log Shutdown Hook
|
||||
In order to release logging resources when your application terminates, a shutdown hook that will trigger log system cleanup when the JVM exits is provided.
|
||||
This shutdown hook is registered automatically unless your application is deployed as a war file.
|
||||
If your application has complex context hierarchies the shutdown hook may not meet your needs.
|
||||
If it does not, disable the shutdown hook and investigate the options provided directly by the underlying logging system.
|
||||
For example, Logback offers http://logback.qos.ch/manual/loggingSeparation.html[context selectors] which allow each Logger to be created in its own context.
|
||||
You can use the configprop:logging.register-shutdown-hook[] property to disable the shutdown hook.
|
||||
Setting it to `false` will disable the registration.
|
||||
You can set the property in your `application.properties` or `application.yaml` file:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
logging:
|
||||
register-shutdown-hook: false
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.logging.custom-log-configuration]]
|
||||
=== Custom Log Configuration
|
||||
The various logging systems can be activated by including the appropriate libraries on the classpath and can be further customized by providing a suitable configuration file in the root of the classpath or in a location specified by the following Spring `Environment` property: configprop:logging.config[].
|
||||
|
||||
You can force Spring Boot to use a particular logging system by using the `org.springframework.boot.logging.LoggingSystem` system property.
|
||||
The value should be the fully qualified class name of a `LoggingSystem` implementation.
|
||||
You can also disable Spring Boot's logging configuration entirely by using a value of `none`.
|
||||
|
||||
NOTE: Since logging is initialized *before* the `ApplicationContext` is created, it is not possible to control logging from `@PropertySources` in Spring `@Configuration` files.
|
||||
The only way to change the logging system or disable it entirely is via System properties.
|
||||
|
||||
Depending on your logging system, the following files are loaded:
|
||||
|
||||
|===
|
||||
| Logging System | Customization
|
||||
|
||||
| Logback
|
||||
| `logback-spring.xml`, `logback-spring.groovy`, `logback.xml`, or `logback.groovy`
|
||||
|
||||
| Log4j2
|
||||
| `log4j2-spring.xml` or `log4j2.xml`
|
||||
|
||||
| JDK (Java Util Logging)
|
||||
| `logging.properties`
|
||||
|===
|
||||
|
||||
NOTE: When possible, we recommend that you use the `-spring` variants for your logging configuration (for example, `logback-spring.xml` rather than `logback.xml`).
|
||||
If you use standard configuration locations, Spring cannot completely control log initialization.
|
||||
|
||||
WARNING: There are known classloading issues with Java Util Logging that cause problems when running from an 'executable jar'.
|
||||
We recommend that you avoid it when running from an 'executable jar' if at all possible.
|
||||
|
||||
To help with the customization, some other properties are transferred from the Spring `Environment` to System properties, as described in the following table:
|
||||
|
||||
|===
|
||||
| Spring Environment | System Property | Comments
|
||||
|
||||
| configprop:logging.exception-conversion-word[]
|
||||
| `LOG_EXCEPTION_CONVERSION_WORD`
|
||||
| The conversion word used when logging exceptions.
|
||||
|
||||
| configprop:logging.file.name[]
|
||||
| `LOG_FILE`
|
||||
| If defined, it is used in the default log configuration.
|
||||
|
||||
| configprop:logging.file.path[]
|
||||
| `LOG_PATH`
|
||||
| If defined, it is used in the default log configuration.
|
||||
|
||||
| configprop:logging.pattern.console[]
|
||||
| `CONSOLE_LOG_PATTERN`
|
||||
| The log pattern to use on the console (stdout).
|
||||
|
||||
| configprop:logging.pattern.dateformat[]
|
||||
| `LOG_DATEFORMAT_PATTERN`
|
||||
| Appender pattern for log date format.
|
||||
|
||||
| configprop:logging.charset.console[]
|
||||
| `CONSOLE_LOG_CHARSET`
|
||||
| The charset to use for console logging.
|
||||
|
||||
| configprop:logging.pattern.file[]
|
||||
| `FILE_LOG_PATTERN`
|
||||
| The log pattern to use in a file (if `LOG_FILE` is enabled).
|
||||
|
||||
| configprop:logging.charset.file[]
|
||||
| `FILE_LOG_CHARSET`
|
||||
| The charset to use for file logging (if `LOG_FILE` is enabled).
|
||||
|
||||
| configprop:logging.pattern.level[]
|
||||
| `LOG_LEVEL_PATTERN`
|
||||
| The format to use when rendering the log level (default `%5p`).
|
||||
|
||||
| `PID`
|
||||
| `PID`
|
||||
| The current process ID (discovered if possible and when not already defined as an OS environment variable).
|
||||
|===
|
||||
|
||||
If you're using Logback, the following properties are also transferred:
|
||||
|
||||
|===
|
||||
| Spring Environment | System Property | Comments
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.file-name-pattern[]
|
||||
| `LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN`
|
||||
| Pattern for rolled-over log file names (default `$\{LOG_FILE}.%d\{yyyy-MM-dd}.%i.gz`).
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.clean-history-on-start[]
|
||||
| `LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START`
|
||||
| Whether to clean the archive log files on startup.
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.max-file-size[]
|
||||
| `LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE`
|
||||
| Maximum log file size.
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.total-size-cap[]
|
||||
| `LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP`
|
||||
| Total size of log backups to be kept.
|
||||
|
||||
| configprop:logging.logback.rollingpolicy.max-history[]
|
||||
| `LOGBACK_ROLLINGPOLICY_MAX_HISTORY`
|
||||
| Maximum number of archive log files to keep.
|
||||
|===
|
||||
|
||||
|
||||
All the supported logging systems can consult System properties when parsing their configuration files.
|
||||
See the default configurations in `spring-boot.jar` for examples:
|
||||
|
||||
* {spring-boot-code}/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/logback/defaults.xml[Logback]
|
||||
* {spring-boot-code}/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/log4j2/log4j2.xml[Log4j 2]
|
||||
* {spring-boot-code}/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/java/logging-file.properties[Java Util logging]
|
||||
|
||||
[TIP]
|
||||
====
|
||||
If you want to use a placeholder in a logging property, you should use <<features#features.external-config.files.property-placeholders,Spring Boot's syntax>> and not the syntax of the underlying framework.
|
||||
Notably, if you use Logback, you should use `:` as the delimiter between a property name and its default value and not use `:-`.
|
||||
====
|
||||
|
||||
[TIP]
|
||||
====
|
||||
You can add MDC and other ad-hoc content to log lines by overriding only the `LOG_LEVEL_PATTERN` (or `logging.pattern.level` with Logback).
|
||||
For example, if you use `logging.pattern.level=user:%X\{user} %5p`, then the default log format contains an MDC entry for "user", if it exists, as shown in the following example.
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
2019-08-30 12:30:04.031 user:someone INFO 22174 --- [ nio-8080-exec-0] demo.Controller
|
||||
Handling authenticated request
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[features.logging.logback-extensions]]
|
||||
=== Logback Extensions
|
||||
Spring Boot includes a number of extensions to Logback that can help with advanced configuration.
|
||||
You can use these extensions in your `logback-spring.xml` configuration file.
|
||||
|
||||
NOTE: Because the standard `logback.xml` configuration file is loaded too early, you cannot use extensions in it.
|
||||
You need to either use `logback-spring.xml` or define a configprop:logging.config[] property.
|
||||
|
||||
WARNING: The extensions cannot be used with Logback's https://logback.qos.ch/manual/configuration.html#autoScan[configuration scanning].
|
||||
If you attempt to do so, making changes to the configuration file results in an error similar to one of the following being logged:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]]
|
||||
ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.logging.logback-extensions.profile-specific]]
|
||||
==== Profile-specific Configuration
|
||||
The `<springProfile>` tag lets you optionally include or exclude sections of configuration based on the active Spring profiles.
|
||||
Profile sections are supported anywhere within the `<configuration>` element.
|
||||
Use the `name` attribute to specify which profile accepts the configuration.
|
||||
The `<springProfile>` tag can contain a profile name (for example `staging`) or a profile expression.
|
||||
A profile expression allows for more complicated profile logic to be expressed, for example `production & (eu-central | eu-west)`.
|
||||
Check the {spring-framework-docs}/core.html#beans-definition-profiles-java[reference guide] for more details.
|
||||
The following listing shows three sample profiles:
|
||||
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<springProfile name="staging">
|
||||
<!-- configuration to be enabled when the "staging" profile is active -->
|
||||
</springProfile>
|
||||
|
||||
<springProfile name="dev | staging">
|
||||
<!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
|
||||
</springProfile>
|
||||
|
||||
<springProfile name="!production">
|
||||
<!-- configuration to be enabled when the "production" profile is not active -->
|
||||
</springProfile>
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.logging.logback-extensions.environment-properties]]
|
||||
==== Environment Properties
|
||||
The `<springProperty>` tag lets you expose properties from the Spring `Environment` for use within Logback.
|
||||
Doing so can be useful if you want to access values from your `application.properties` file in your Logback configuration.
|
||||
The tag works in a similar way to Logback's standard `<property>` tag.
|
||||
However, rather than specifying a direct `value`, you specify the `source` of the property (from the `Environment`).
|
||||
If you need to store the property somewhere other than in `local` scope, you can use the `scope` attribute.
|
||||
If you need a fallback value (in case the property is not set in the `Environment`), you can use the `defaultValue` attribute.
|
||||
The following example shows how to expose properties for use within Logback:
|
||||
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
<springProperty scope="context" name="fluentHost" source="myapp.fluentd.host"
|
||||
defaultValue="localhost"/>
|
||||
<appender name="FLUENT" class="ch.qos.logback.more.appenders.DataFluentAppender">
|
||||
<remoteHost>${fluentHost}</remoteHost>
|
||||
...
|
||||
</appender>
|
||||
----
|
||||
|
||||
NOTE: The `source` must be specified in kebab case (such as `my.property-name`).
|
||||
However, properties can be added to the `Environment` by using the relaxed rules.
|
||||
|
|
@ -0,0 +1,492 @@
|
|||
[[features.messaging]]
|
||||
== Messaging
|
||||
The Spring Framework provides extensive support for integrating with messaging systems, from simplified use of the JMS API using `JmsTemplate` to a complete infrastructure to receive messages asynchronously.
|
||||
Spring AMQP provides a similar feature set for the Advanced Message Queuing Protocol.
|
||||
Spring Boot also provides auto-configuration options for `RabbitTemplate` and RabbitMQ.
|
||||
Spring WebSocket natively includes support for STOMP messaging, and Spring Boot has support for that through starters and a small amount of auto-configuration.
|
||||
Spring Boot also has support for Apache Kafka.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.jms]]
|
||||
=== JMS
|
||||
The `javax.jms.ConnectionFactory` interface provides a standard method of creating a `javax.jms.Connection` for interacting with a JMS broker.
|
||||
Although Spring needs a `ConnectionFactory` to work with JMS, you generally need not use it directly yourself and can instead rely on higher level messaging abstractions.
|
||||
(See the {spring-framework-docs}/integration.html#jms[relevant section] of the Spring Framework reference documentation for details.)
|
||||
Spring Boot also auto-configures the necessary infrastructure to send and receive messages.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.jms.activemq]]
|
||||
==== ActiveMQ Support
|
||||
When https://activemq.apache.org/[ActiveMQ] is available on the classpath, Spring Boot can also configure a `ConnectionFactory`.
|
||||
If the broker is present, an embedded broker is automatically started and configured (provided no broker URL is specified through configuration).
|
||||
|
||||
NOTE: If you use `spring-boot-starter-activemq`, the necessary dependencies to connect or embed an ActiveMQ instance are provided, as is the Spring infrastructure to integrate with JMS.
|
||||
|
||||
ActiveMQ configuration is controlled by external configuration properties in `+spring.activemq.*+`.
|
||||
For example, you might declare the following section in `application.properties`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
activemq:
|
||||
broker-url: "tcp://192.168.1.210:9876"
|
||||
user: "admin"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
jms:
|
||||
cache:
|
||||
session-cache-size: 5
|
||||
----
|
||||
|
||||
If you'd rather use native pooling, you can do so by adding a dependency to `org.messaginghub:pooled-jms` and configuring the `JmsPoolConnectionFactory` accordingly, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
activemq:
|
||||
pool:
|
||||
enabled: true
|
||||
max-connections: 50
|
||||
----
|
||||
|
||||
TIP: See {spring-boot-autoconfigure-module-code}/jms/activemq/ActiveMQProperties.java[`ActiveMQProperties`] for more of the supported options.
|
||||
You can also register an arbitrary number of beans that implement `ActiveMQConnectionFactoryCustomizer` for more advanced customizations.
|
||||
|
||||
By default, ActiveMQ creates a destination if it does not yet exist so that destinations are resolved against their provided names.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.jms.artemis]]
|
||||
==== ActiveMQ Artemis Support
|
||||
Spring Boot can auto-configure a `ConnectionFactory` when it detects that https://activemq.apache.org/components/artemis/[ActiveMQ Artemis] is available on the classpath.
|
||||
If the broker is present, an embedded broker is automatically started and configured (unless the mode property has been explicitly set).
|
||||
The supported modes are `embedded` (to make explicit that an embedded broker is required and that an error should occur if the broker is not available on the classpath) and `native` (to connect to a broker using the `netty` transport protocol).
|
||||
When the latter is configured, Spring Boot configures a `ConnectionFactory` that connects to a broker running on the local machine with the default settings.
|
||||
|
||||
NOTE: If you use `spring-boot-starter-artemis`, the necessary dependencies to connect to an existing ActiveMQ Artemis instance are provided, as well as the Spring infrastructure to integrate with JMS.
|
||||
Adding `org.apache.activemq:artemis-jms-server` to your application lets you use embedded mode.
|
||||
|
||||
ActiveMQ Artemis configuration is controlled by external configuration properties in `+spring.artemis.*+`.
|
||||
For example, you might declare the following section in `application.properties`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
artemis:
|
||||
mode: native
|
||||
broker-url: "tcp://192.168.1.210:9876"
|
||||
user: "admin"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
When embedding the broker, you can choose if you want to enable persistence and list the destinations that should be made available.
|
||||
These can be specified as a comma-separated list to create them with the default options, or you can define bean(s) of type `org.apache.activemq.artemis.jms.server.config.JMSQueueConfiguration` or `org.apache.activemq.artemis.jms.server.config.TopicConfiguration`, for advanced queue and topic configurations, respectively.
|
||||
|
||||
By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
jms:
|
||||
cache:
|
||||
session-cache-size: 5
|
||||
----
|
||||
|
||||
If you'd rather use native pooling, you can do so by adding a dependency to `org.messaginghub:pooled-jms` and configuring the `JmsPoolConnectionFactory` accordingly, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
artemis:
|
||||
pool:
|
||||
enabled: true
|
||||
max-connections: 50
|
||||
----
|
||||
|
||||
See {spring-boot-autoconfigure-module-code}/jms/artemis/ArtemisProperties.java[`ArtemisProperties`] for more supported options.
|
||||
|
||||
No JNDI lookup is involved, and destinations are resolved against their names, using either the `name` attribute in the Artemis configuration or the names provided through configuration.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.jms.jndi]]
|
||||
==== Using a JNDI ConnectionFactory
|
||||
If you are running your application in an application server, Spring Boot tries to locate a JMS `ConnectionFactory` by using JNDI.
|
||||
By default, the `java:/JmsXA` and `java:/XAConnectionFactory` location are checked.
|
||||
You can use the configprop:spring.jms.jndi-name[] property if you need to specify an alternative location, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
jms:
|
||||
jndi-name: "java:/MyConnectionFactory"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.messaging.jms.sending]]
|
||||
==== Sending a Message
|
||||
Spring's `JmsTemplate` is auto-configured, and you can autowire it directly into your own beans, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/jms/template/MyBean.java[]
|
||||
----
|
||||
|
||||
NOTE: {spring-framework-api}/jms/core/JmsMessagingTemplate.html[`JmsMessagingTemplate`] can be injected in a similar manner.
|
||||
If a `DestinationResolver` or a `MessageConverter` bean is defined, it is associated automatically to the auto-configured `JmsTemplate`.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.jms.receiving]]
|
||||
==== Receiving a Message
|
||||
When the JMS infrastructure is present, any bean can be annotated with `@JmsListener` to create a listener endpoint.
|
||||
If no `JmsListenerContainerFactory` has been defined, a default one is configured automatically.
|
||||
If a `DestinationResolver`, a `MessageConverter`, or a `javax.jms.ExceptionListener` beans are defined, they are associated automatically with the default factory.
|
||||
|
||||
By default, the default factory is transactional.
|
||||
If you run in an infrastructure where a `JtaTransactionManager` is present, it is associated to the listener container by default.
|
||||
If not, the `sessionTransacted` flag is enabled.
|
||||
In that latter scenario, you can associate your local data store transaction to the processing of an incoming message by adding `@Transactional` on your listener method (or a delegate thereof).
|
||||
This ensures that the incoming message is acknowledged, once the local transaction has completed.
|
||||
This also includes sending response messages that have been performed on the same JMS session.
|
||||
|
||||
The following component creates a listener endpoint on the `someQueue` destination:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/jms/receiving/MyBean.java[]
|
||||
----
|
||||
|
||||
TIP: See {spring-framework-api}/jms/annotation/EnableJms.html[the Javadoc of `@EnableJms`] for more details.
|
||||
|
||||
If you need to create more `JmsListenerContainerFactory` instances or if you want to override the default, Spring Boot provides a `DefaultJmsListenerContainerFactoryConfigurer` that you can use to initialize a `DefaultJmsListenerContainerFactory` with the same settings as the one that is auto-configured.
|
||||
|
||||
For instance, the following example exposes another factory that uses a specific `MessageConverter`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/jms/receiving/custom/JmsConfiguration.java[]
|
||||
----
|
||||
|
||||
Then you can use the factory in any `@JmsListener`-annotated method as follows:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/jms/receiving/custom/MyBean.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.messaging.amqp]]
|
||||
=== AMQP
|
||||
The Advanced Message Queuing Protocol (AMQP) is a platform-neutral, wire-level protocol for message-oriented middleware.
|
||||
The Spring AMQP project applies core Spring concepts to the development of AMQP-based messaging solutions.
|
||||
Spring Boot offers several conveniences for working with AMQP through RabbitMQ, including the `spring-boot-starter-amqp` "`Starter`".
|
||||
|
||||
|
||||
|
||||
[[features.messaging.amqp.rabbitmq]]
|
||||
==== RabbitMQ support
|
||||
https://www.rabbitmq.com/[RabbitMQ] is a lightweight, reliable, scalable, and portable message broker based on the AMQP protocol.
|
||||
Spring uses `RabbitMQ` to communicate through the AMQP protocol.
|
||||
|
||||
RabbitMQ configuration is controlled by external configuration properties in `+spring.rabbitmq.*+`.
|
||||
For example, you might declare the following section in `application.properties`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rabbitmq:
|
||||
host: "localhost"
|
||||
port: 5672
|
||||
username: "admin"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
Alternatively, you could configure the same connection using the `addresses` attribute:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rabbitmq:
|
||||
addresses: "amqp://admin:secret@localhost"
|
||||
----
|
||||
|
||||
NOTE: When specifying addresses that way, the `host` and `port` properties are ignored.
|
||||
If the address uses the `amqps` protocol, SSL support is enabled automatically.
|
||||
|
||||
See {spring-boot-autoconfigure-module-code}/amqp/RabbitProperties.java[`RabbitProperties`] for more of the supported property-based configuration options.
|
||||
To configure lower-level details of the RabbitMQ `ConnectionFactory` that is used by Spring AMQP, define a `ConnectionFactoryCustomizer` bean.
|
||||
|
||||
If a `ConnectionNameStrategy` bean exists in the context, it will be automatically used to name connections created by the auto-configured `CachingConnectionFactory`.
|
||||
|
||||
TIP: See https://spring.io/blog/2010/06/14/understanding-amqp-the-protocol-used-by-rabbitmq/[Understanding AMQP, the protocol used by RabbitMQ] for more details.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.amqp.sending]]
|
||||
==== Sending a Message
|
||||
Spring's `AmqpTemplate` and `AmqpAdmin` are auto-configured, and you can autowire them directly into your own beans, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/amqp/sending/MyBean.java[]
|
||||
----
|
||||
|
||||
NOTE: {spring-amqp-api}/rabbit/core/RabbitMessagingTemplate.html[`RabbitMessagingTemplate`] can be injected in a similar manner.
|
||||
If a `MessageConverter` bean is defined, it is associated automatically to the auto-configured `AmqpTemplate`.
|
||||
|
||||
If necessary, any `org.springframework.amqp.core.Queue` that is defined as a bean is automatically used to declare a corresponding queue on the RabbitMQ instance.
|
||||
|
||||
To retry operations, you can enable retries on the `AmqpTemplate` (for example, in the event that the broker connection is lost):
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rabbitmq:
|
||||
template:
|
||||
retry:
|
||||
enabled: true
|
||||
initial-interval: "2s"
|
||||
----
|
||||
|
||||
Retries are disabled by default.
|
||||
You can also customize the `RetryTemplate` programmatically by declaring a `RabbitRetryTemplateCustomizer` bean.
|
||||
|
||||
If you need to create more `RabbitTemplate` instances or if you want to override the default, Spring Boot provides a `RabbitTemplateConfigurer` bean that you can use to initialize a `RabbitTemplate` with the same settings as the factories used by the auto-configuration.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.amqp.receiving]]
|
||||
==== Receiving a Message
|
||||
When the Rabbit infrastructure is present, any bean can be annotated with `@RabbitListener` to create a listener endpoint.
|
||||
If no `RabbitListenerContainerFactory` has been defined, a default `SimpleRabbitListenerContainerFactory` is automatically configured and you can switch to a direct container using the configprop:spring.rabbitmq.listener.type[] property.
|
||||
If a `MessageConverter` or a `MessageRecoverer` bean is defined, it is automatically associated with the default factory.
|
||||
|
||||
The following sample component creates a listener endpoint on the `someQueue` queue:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/amqp/receiving/MyBean.java[]
|
||||
----
|
||||
|
||||
TIP: See {spring-amqp-api}/rabbit/annotation/EnableRabbit.html[the Javadoc of `@EnableRabbit`] for more details.
|
||||
|
||||
If you need to create more `RabbitListenerContainerFactory` instances or if you want to override the default, Spring Boot provides a `SimpleRabbitListenerContainerFactoryConfigurer` and a `DirectRabbitListenerContainerFactoryConfigurer` that you can use to initialize a `SimpleRabbitListenerContainerFactory` and a `DirectRabbitListenerContainerFactory` with the same settings as the factories used by the auto-configuration.
|
||||
|
||||
TIP: It does not matter which container type you chose.
|
||||
Those two beans are exposed by the auto-configuration.
|
||||
|
||||
For instance, the following configuration class exposes another factory that uses a specific `MessageConverter`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/amqp/receiving/custom/RabbitConfiguration.java[]
|
||||
----
|
||||
|
||||
Then you can use the factory in any `@RabbitListener`-annotated method, as follows:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/amqp/receiving/custom/MyBean.java[]
|
||||
----
|
||||
|
||||
You can enable retries to handle situations where your listener throws an exception.
|
||||
By default, `RejectAndDontRequeueRecoverer` is used, but you can define a `MessageRecoverer` of your own.
|
||||
When retries are exhausted, the message is rejected and either dropped or routed to a dead-letter exchange if the broker is configured to do so.
|
||||
By default, retries are disabled.
|
||||
You can also customize the `RetryTemplate` programmatically by declaring a `RabbitRetryTemplateCustomizer` bean.
|
||||
|
||||
IMPORTANT: By default, if retries are disabled and the listener throws an exception, the delivery is retried indefinitely.
|
||||
You can modify this behavior in two ways: Set the `defaultRequeueRejected` property to `false` so that zero re-deliveries are attempted or throw an `AmqpRejectAndDontRequeueException` to signal the message should be rejected.
|
||||
The latter is the mechanism used when retries are enabled and the maximum number of delivery attempts is reached.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.kafka]]
|
||||
=== Apache Kafka Support
|
||||
https://kafka.apache.org/[Apache Kafka] is supported by providing auto-configuration of the `spring-kafka` project.
|
||||
|
||||
Kafka configuration is controlled by external configuration properties in `spring.kafka.*`.
|
||||
For example, you might declare the following section in `application.properties`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
bootstrap-servers: "localhost:9092"
|
||||
consumer:
|
||||
group-id: "myGroup"
|
||||
----
|
||||
|
||||
TIP: To create a topic on startup, add a bean of type `NewTopic`.
|
||||
If the topic already exists, the bean is ignored.
|
||||
|
||||
See {spring-boot-autoconfigure-module-code}/kafka/KafkaProperties.java[`KafkaProperties`] for more supported options.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.kafka.sending]]
|
||||
==== Sending a Message
|
||||
Spring's `KafkaTemplate` is auto-configured, and you can autowire it directly in your own beans, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/kafka/sending/MyBean.java[]
|
||||
----
|
||||
|
||||
NOTE: If the property configprop:spring.kafka.producer.transaction-id-prefix[] is defined, a `KafkaTransactionManager` is automatically configured.
|
||||
Also, if a `RecordMessageConverter` bean is defined, it is automatically associated to the auto-configured `KafkaTemplate`.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.kafka.receiving]]
|
||||
==== Receiving a Message
|
||||
When the Apache Kafka infrastructure is present, any bean can be annotated with `@KafkaListener` to create a listener endpoint.
|
||||
If no `KafkaListenerContainerFactory` has been defined, a default one is automatically configured with keys defined in `spring.kafka.listener.*`.
|
||||
|
||||
The following component creates a listener endpoint on the `someTopic` topic:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/kafka/receiving/MyBean.java[]
|
||||
----
|
||||
|
||||
If a `KafkaTransactionManager` bean is defined, it is automatically associated to the container factory.
|
||||
Similarly, if a `RecordFilterStrategy`, `ErrorHandler`, `AfterRollbackProcessor` or `ConsumerAwareRebalanceListener` bean is defined, it is automatically associated to the default factory.
|
||||
|
||||
Depending on the listener type, a `RecordMessageConverter` or `BatchMessageConverter` bean is associated to the default factory.
|
||||
If only a `RecordMessageConverter` bean is present for a batch listener, it is wrapped in a `BatchMessageConverter`.
|
||||
|
||||
TIP: A custom `ChainedKafkaTransactionManager` must be marked `@Primary` as it usually references the auto-configured `KafkaTransactionManager` bean.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.kafka.streams]]
|
||||
==== Kafka Streams
|
||||
Spring for Apache Kafka provides a factory bean to create a `StreamsBuilder` object and manage the lifecycle of its streams.
|
||||
Spring Boot auto-configures the required `KafkaStreamsConfiguration` bean as long as `kafka-streams` is on the classpath and Kafka Streams is enabled via the `@EnableKafkaStreams` annotation.
|
||||
|
||||
Enabling Kafka Streams means that the application id and bootstrap servers must be set.
|
||||
The former can be configured using `spring.kafka.streams.application-id`, defaulting to `spring.application.name` if not set.
|
||||
The latter can be set globally or specifically overridden only for streams.
|
||||
|
||||
Several additional properties are available using dedicated properties; other arbitrary Kafka properties can be set using the `spring.kafka.streams.properties` namespace.
|
||||
See also <<features#features.messaging.kafka.additional-properties>> for more information.
|
||||
|
||||
To use the factory bean, wire `StreamsBuilder` into your `@Bean` as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/KafkaStreamsConfiguration.java[]
|
||||
----
|
||||
|
||||
By default, the streams managed by the `StreamBuilder` object it creates are started automatically.
|
||||
You can customize this behaviour using the configprop:spring.kafka.streams.auto-startup[] property.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.kafka.additional-properties]]
|
||||
==== Additional Kafka Properties
|
||||
The properties supported by auto configuration are shown in <<application-properties#application-properties>>.
|
||||
Note that, for the most part, these properties (hyphenated or camelCase) map directly to the Apache Kafka dotted properties.
|
||||
Refer to the Apache Kafka documentation for details.
|
||||
|
||||
The first few of these properties apply to all components (producers, consumers, admins, and streams) but can be specified at the component level if you wish to use different values.
|
||||
Apache Kafka designates properties with an importance of HIGH, MEDIUM, or LOW.
|
||||
Spring Boot auto-configuration supports all HIGH importance properties, some selected MEDIUM and LOW properties, and any properties that do not have a default value.
|
||||
|
||||
Only a subset of the properties supported by Kafka are available directly through the `KafkaProperties` class.
|
||||
If you wish to configure the producer or consumer with additional properties that are not directly supported, use the following properties:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
properties:
|
||||
"[prop.one]": "first"
|
||||
admin:
|
||||
properties:
|
||||
"[prop.two]": "second"
|
||||
consumer:
|
||||
properties:
|
||||
"[prop.three]": "third"
|
||||
producer:
|
||||
properties:
|
||||
"[prop.four]": "fourth"
|
||||
streams:
|
||||
properties:
|
||||
"[prop.five]": "fifth"
|
||||
----
|
||||
|
||||
This sets the common `prop.one` Kafka property to `first` (applies to producers, consumers and admins), the `prop.two` admin property to `second`, the `prop.three` consumer property to `third`, the `prop.four` producer property to `fourth` and the `prop.five` streams property to `fifth`.
|
||||
|
||||
You can also configure the Spring Kafka `JsonDeserializer` as follows:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
consumer:
|
||||
value-deserializer: "org.springframework.kafka.support.serializer.JsonDeserializer"
|
||||
properties:
|
||||
"[spring.json.value.default.type]": "com.example.Invoice"
|
||||
"[spring.json.trusted.packages]": "com.example,org.acme"
|
||||
----
|
||||
|
||||
Similarly, you can disable the `JsonSerializer` default behavior of sending type information in headers:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
producer:
|
||||
value-serializer: "org.springframework.kafka.support.serializer.JsonSerializer"
|
||||
properties:
|
||||
"[spring.json.add.type.headers]": false
|
||||
----
|
||||
|
||||
IMPORTANT: Properties set in this way override any configuration item that Spring Boot explicitly supports.
|
||||
|
||||
|
||||
|
||||
[[features.messaging.kafka.embedded]]
|
||||
==== Testing with Embedded Kafka
|
||||
Spring for Apache Kafka provides a convenient way to test projects with an embedded Apache Kafka broker.
|
||||
To use this feature, annotate a test class with `@EmbeddedKafka` from the `spring-kafka-test` module.
|
||||
For more information, please see the Spring for Apache Kafka {spring-kafka-docs}#embedded-kafka-annotation[reference manual].
|
||||
|
||||
To make Spring Boot auto-configuration work with the aforementioned embedded Apache Kafka broker, you need to remap a system property for embedded broker addresses (populated by the `EmbeddedKafkaBroker`) into the Spring Boot configuration property for Apache Kafka.
|
||||
There are several ways to do that:
|
||||
|
||||
* Provide a system property to map embedded broker addresses into configprop:spring.kafka.bootstrap-servers[] in the test class:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/kafka/test/property/MyTest.java[tag=*]
|
||||
----
|
||||
|
||||
* Configure a property name on the `@EmbeddedKafka` annotation:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/messaging/kafka/test/annotation/MyTest.java[]
|
||||
----
|
||||
|
||||
* Use a placeholder in configuration properties:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
bootstrap-servers: "${spring.embedded.kafka.brokers}"
|
||||
----
|
||||
|
|
@ -0,0 +1,644 @@
|
|||
[[features.nosql]]
|
||||
== Working with NoSQL Technologies
|
||||
Spring Data provides additional projects that help you access a variety of NoSQL technologies, including:
|
||||
|
||||
* {spring-data-mongodb}[MongoDB]
|
||||
* {spring-data-neo4j}[Neo4J]
|
||||
* {spring-data-elasticsearch}[Elasticsearch]
|
||||
* {spring-data-redis}[Redis]
|
||||
* {spring-data-gemfire}[GemFire] or {spring-data-geode}[Geode]
|
||||
* {spring-data-cassandra}[Cassandra]
|
||||
* {spring-data-couchbase}[Couchbase]
|
||||
* {spring-data-ldap}[LDAP]
|
||||
|
||||
Spring Boot provides auto-configuration for Redis, MongoDB, Neo4j, Elasticsearch, Solr Cassandra, Couchbase, and LDAP.
|
||||
You can make use of the other projects, but you must configure them yourself.
|
||||
Refer to the appropriate reference documentation at {spring-data}.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.redis]]
|
||||
=== Redis
|
||||
https://redis.io/[Redis] is a cache, message broker, and richly-featured key-value store.
|
||||
Spring Boot offers basic auto-configuration for the https://github.com/lettuce-io/lettuce-core/[Lettuce] and https://github.com/xetorthio/jedis/[Jedis] client libraries and the abstractions on top of them provided by https://github.com/spring-projects/spring-data-redis[Spring Data Redis].
|
||||
|
||||
There is a `spring-boot-starter-data-redis` "`Starter`" for collecting the dependencies in a convenient way.
|
||||
By default, it uses https://github.com/lettuce-io/lettuce-core/[Lettuce].
|
||||
That starter handles both traditional and reactive applications.
|
||||
|
||||
TIP: We also provide a `spring-boot-starter-data-redis-reactive` "`Starter`" for consistency with the other stores with reactive support.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.redis.connecting]]
|
||||
==== Connecting to Redis
|
||||
You can inject an auto-configured `RedisConnectionFactory`, `StringRedisTemplate`, or vanilla `RedisTemplate` instance as you would any other Spring Bean.
|
||||
By default, the instance tries to connect to a Redis server at `localhost:6379`.
|
||||
The following listing shows an example of such a bean:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/redis/MyBean.java[]
|
||||
----
|
||||
|
||||
TIP: You can also register an arbitrary number of beans that implement `LettuceClientConfigurationBuilderCustomizer` for more advanced customizations.
|
||||
If you use Jedis, `JedisClientConfigurationBuilderCustomizer` is also available.
|
||||
|
||||
If you add your own `@Bean` of any of the auto-configured types, it replaces the default (except in the case of `RedisTemplate`, when the exclusion is based on the bean name, `redisTemplate`, not its type).
|
||||
By default, if `commons-pool2` is on the classpath, you get a pooled connection factory.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.mongodb]]
|
||||
=== MongoDB
|
||||
https://www.mongodb.com/[MongoDB] is an open-source NoSQL document database that uses a JSON-like schema instead of traditional table-based relational data.
|
||||
Spring Boot offers several conveniences for working with MongoDB, including the `spring-boot-starter-data-mongodb` and `spring-boot-starter-data-mongodb-reactive` "`Starters`".
|
||||
|
||||
|
||||
|
||||
[[features.nosql.mongodb.connecting]]
|
||||
==== Connecting to a MongoDB Database
|
||||
To access MongoDB databases, you can inject an auto-configured `org.springframework.data.mongodb.MongoDatabaseFactory`.
|
||||
By default, the instance tries to connect to a MongoDB server at `mongodb://localhost/test`.
|
||||
The following example shows how to connect to a MongoDB database:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/mongodb/databasefactory/MyBean.java[]
|
||||
----
|
||||
|
||||
If you have defined your own `MongoClient`, it will be used to auto-configure a suitable `MongoDatabaseFactory`.
|
||||
|
||||
The auto-configured `MongoClient` is created using a `MongoClientSettings` bean.
|
||||
If you have defined your own `MongoClientSettings`, it will be used without modification and the `spring.data.mongodb` properties will be ignored.
|
||||
Otherwise a `MongoClientSettings` will be auto-configured and will have the `spring.data.mongodb` properties applied to it.
|
||||
In either case, you can declare one or more `MongoClientSettingsBuilderCustomizer` beans to fine-tune the `MongoClientSettings` configuration.
|
||||
Each will be called in order with the `MongoClientSettings.Builder` that is used to build the `MongoClientSettings`.
|
||||
|
||||
You can set the configprop:spring.data.mongodb.uri[] property to change the URL and configure additional settings such as the _replica set_, as shown in the following example:
|
||||
|
||||
[source,properties,indent=0,configprops]
|
||||
----
|
||||
spring.data.mongodb.uri=mongodb://user:secret@mongo1.example.com:12345,mongo2.example.com:23456/test
|
||||
----
|
||||
|
||||
Alternatively, you can specify connection details using discrete properties.
|
||||
For example, you might declare the following settings in your `application.properties`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
data:
|
||||
mongodb:
|
||||
host: "mongoserver.example.com"
|
||||
port: 27017
|
||||
database: "test"
|
||||
username: "user"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
TIP: If `spring.data.mongodb.port` is not specified, the default of `27017` is used.
|
||||
You could delete this line from the example shown earlier.
|
||||
|
||||
TIP: If you do not use Spring Data MongoDB, you can inject a `MongoClient` bean instead of using `MongoDatabaseFactory`.
|
||||
If you want to take complete control of establishing the MongoDB connection, you can also declare your own `MongoDatabaseFactory` or `MongoClient` bean.
|
||||
|
||||
NOTE: If you are using the reactive driver, Netty is required for SSL.
|
||||
The auto-configuration configures this factory automatically if Netty is available and the factory to use hasn't been customized already.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.mongodb.template]]
|
||||
==== MongoTemplate
|
||||
{spring-data-mongodb}[Spring Data MongoDB] provides a {spring-data-mongodb-api}/core/MongoTemplate.html[`MongoTemplate`] class that is very similar in its design to Spring's `JdbcTemplate`.
|
||||
As with `JdbcTemplate`, Spring Boot auto-configures a bean for you to inject the template, as follows:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/mongodb/template/MyBean.java[]
|
||||
----
|
||||
|
||||
See the {spring-data-mongodb-api}/core/MongoOperations.html[`MongoOperations` Javadoc] for complete details.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.mongodb.repositories]]
|
||||
[[features.nosql.mongodb.repositories]]
|
||||
==== Spring Data MongoDB Repositories
|
||||
Spring Data includes repository support for MongoDB.
|
||||
As with the JPA repositories discussed earlier, the basic principle is that queries are constructed automatically, based on method names.
|
||||
|
||||
In fact, both Spring Data JPA and Spring Data MongoDB share the same common infrastructure.
|
||||
You could take the JPA example from earlier and, assuming that `City` is now a MongoDB data class rather than a JPA `@Entity`, it works in the same way, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/mongodb/data/CityRepository.java[]
|
||||
----
|
||||
|
||||
TIP: You can customize document scanning locations by using the `@EntityScan` annotation.
|
||||
|
||||
TIP: For complete details of Spring Data MongoDB, including its rich object mapping technologies, refer to its {spring-data-mongodb}[reference documentation].
|
||||
|
||||
|
||||
|
||||
[[features.nosql.mongodb.embedded]]
|
||||
==== Embedded Mongo
|
||||
Spring Boot offers auto-configuration for https://github.com/flapdoodle-oss/de.flapdoodle.embed.mongo[Embedded Mongo].
|
||||
To use it in your Spring Boot application, add a dependency on `de.flapdoodle.embed:de.flapdoodle.embed.mongo`.
|
||||
|
||||
The port that Mongo listens on can be configured by setting the configprop:spring.data.mongodb.port[] property.
|
||||
To use a randomly allocated free port, use a value of 0.
|
||||
The `MongoClient` created by `MongoAutoConfiguration` is automatically configured to use the randomly allocated port.
|
||||
|
||||
NOTE: If you do not configure a custom port, the embedded support uses a random port (rather than 27017) by default.
|
||||
|
||||
If you have SLF4J on the classpath, the output produced by Mongo is automatically routed to a logger named `org.springframework.boot.autoconfigure.mongo.embedded.EmbeddedMongo`.
|
||||
|
||||
You can declare your own `IMongodConfig` and `IRuntimeConfig` beans to take control of the Mongo instance's configuration and logging routing.
|
||||
The download configuration can be customized by declaring a `DownloadConfigBuilderCustomizer` bean.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.neo4j]]
|
||||
=== Neo4j
|
||||
https://neo4j.com/[Neo4j] is an open-source NoSQL graph database that uses a rich data model of nodes connected by first class relationships, which is better suited for connected big data than traditional RDBMS approaches.
|
||||
Spring Boot offers several conveniences for working with Neo4j, including the `spring-boot-starter-data-neo4j` "`Starter`".
|
||||
|
||||
|
||||
|
||||
[[features.nosql.neo4j.connecting]]
|
||||
==== Connecting to a Neo4j Database
|
||||
To access a Neo4j server, you can inject an auto-configured `org.neo4j.driver.Driver`.
|
||||
By default, the instance tries to connect to a Neo4j server at `localhost:7687` using the Bolt protocol.
|
||||
The following example shows how to inject a Neo4j `Driver` that gives you access, amongst other things, to a `Session`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/neo4j/driver/MyBean.java[]
|
||||
----
|
||||
|
||||
You can configure various aspects of the driver using `spring.neo4j.*` properties.
|
||||
The following example shows how to configure the uri and credentials to use:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
neo4j:
|
||||
uri: "bolt://my-server:7687"
|
||||
authentication:
|
||||
username: "neo4j"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
The auto-configured `Driver` is created using `ConfigBuilder`.
|
||||
To fine-tune its configuration, declare one or more `ConfigBuilderCustomizer` beans.
|
||||
Each will be called in order with the `ConfigBuilder` that is used to build the `Driver`.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.neo4j.repositories]]
|
||||
==== Spring Data Neo4j Repositories
|
||||
Spring Data includes repository support for Neo4j.
|
||||
For complete details of Spring Data Neo4j, refer to the {spring-data-neo4j-docs}[reference documentation].
|
||||
|
||||
Spring Data Neo4j shares the common infrastructure with Spring Data JPA as many other Spring Data modules do.
|
||||
You could take the JPA example from earlier and define `City` as Spring Data Neo4j `@Node` rather than JPA `@Entity` and the repository abstraction works in the same way, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/neo4j/data/CityRepository.java[]
|
||||
----
|
||||
|
||||
The `spring-boot-starter-data-neo4j` "`Starter`" enables the repository support as well as transaction management.
|
||||
Spring Boot supports both classic and reactive Neo4j repositories, using the `Neo4jTemplate` or `ReactiveNeo4jTemplate` beans.
|
||||
When Project Reactor is available on the classpath, the reactive style is also auto-configured.
|
||||
|
||||
You can customize the locations to look for repositories and entities by using `@EnableNeo4jRepositories` and `@EntityScan` respectively on a `@Configuration`-bean.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
In an application using the reactive style, a `ReactiveTransactionManager` is not auto-configured.
|
||||
To enable transaction management, the following bean must be defined in your configuration:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/Neo4jReactiveTransactionManagerConfiguration.java[]
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[features.nosql.solr]]
|
||||
=== Solr
|
||||
https://lucene.apache.org/solr/[Apache Solr] is a search engine.
|
||||
Spring Boot offers basic auto-configuration for the Solr 5 client library.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.solr.connecting]]
|
||||
==== Connecting to Solr
|
||||
You can inject an auto-configured `SolrClient` instance as you would any other Spring bean.
|
||||
By default, the instance tries to connect to a server at `http://localhost:8983/solr`.
|
||||
The following example shows how to inject a Solr bean:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/solr/client/MyBean.java[]
|
||||
----
|
||||
|
||||
If you add your own `@Bean` of type `SolrClient`, it replaces the default.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.elasticsearch]]
|
||||
=== Elasticsearch
|
||||
https://www.elastic.co/products/elasticsearch[Elasticsearch] is an open source, distributed, RESTful search and analytics engine.
|
||||
Spring Boot offers basic auto-configuration for Elasticsearch.
|
||||
|
||||
Spring Boot supports several clients:
|
||||
|
||||
* The official Java "Low Level" and "High Level" REST clients
|
||||
* The `ReactiveElasticsearchClient` provided by Spring Data Elasticsearch
|
||||
|
||||
Spring Boot provides a dedicated "`Starter`", `spring-boot-starter-data-elasticsearch`.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.elasticsearch.connecting-using-rest]]
|
||||
==== Connecting to Elasticsearch using REST clients
|
||||
Elasticsearch ships https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/index.html[two different REST clients] that you can use to query a cluster: the "Low Level" client and the "High Level" client.
|
||||
Spring Boot provides support for the "High Level" client, which ships with `org.elasticsearch.client:elasticsearch-rest-high-level-client`.
|
||||
|
||||
If you have this dependency on the classpath, Spring Boot will auto-configure and register a `RestHighLevelClient` bean that by default targets `http://localhost:9200`.
|
||||
You can further tune how `RestHighLevelClient` is configured, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
elasticsearch:
|
||||
rest:
|
||||
uris: "https://search.example.com:9200"
|
||||
read-timeout: "10s"
|
||||
username: "user"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
You can also register an arbitrary number of beans that implement `RestClientBuilderCustomizer` for more advanced customizations.
|
||||
To take full control over the registration, define a `RestClientBuilder` bean.
|
||||
|
||||
TIP: If your application needs access to a "Low Level" `RestClient`, you can get it by calling `client.getLowLevelClient()` on the auto-configured `RestHighLevelClient`.
|
||||
|
||||
Additionally, if `elasticsearch-rest-client-sniffer` is on the classpath, a `Sniffer` is auto-configured to automatically discover nodes from a running Elasticsearch cluster and set them to the `RestHighLevelClient` bean.
|
||||
You can further tune how `Sniffer` is configured, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
elasticsearch:
|
||||
rest:
|
||||
sniffer:
|
||||
interval: 10m
|
||||
delay-after-failure: 30s
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.nosql.elasticsearch.connecting-using-reactive-rest]]
|
||||
==== Connecting to Elasticsearch using Reactive REST clients
|
||||
{spring-data-elasticsearch}[Spring Data Elasticsearch] ships `ReactiveElasticsearchClient` for querying Elasticsearch instances in a reactive fashion.
|
||||
It is built on top of WebFlux's `WebClient`, so both `spring-boot-starter-elasticsearch` and `spring-boot-starter-webflux` dependencies are useful to enable this support.
|
||||
|
||||
By default, Spring Boot will auto-configure and register a `ReactiveElasticsearchClient`
|
||||
bean that targets `http://localhost:9200`.
|
||||
You can further tune how it is configured, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
data:
|
||||
elasticsearch:
|
||||
client:
|
||||
reactive:
|
||||
endpoints: "search.example.com:9200"
|
||||
use-ssl: true
|
||||
socket-timeout: "10s"
|
||||
username: "user"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
If the configuration properties are not enough and you'd like to fully control the client
|
||||
configuration, you can register a custom `ClientConfiguration` bean.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.elasticsearch.connecting-using-spring-data]]
|
||||
==== Connecting to Elasticsearch by Using Spring Data
|
||||
To connect to Elasticsearch, a `RestHighLevelClient` bean must be defined,
|
||||
auto-configured by Spring Boot or manually provided by the application (see previous sections).
|
||||
With this configuration in place, an
|
||||
`ElasticsearchRestTemplate` can be injected like any other Spring bean,
|
||||
as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/elasticsearch/template/MyBean.java[]
|
||||
----
|
||||
|
||||
In the presence of `spring-data-elasticsearch` and the required dependencies for using a `WebClient` (typically `spring-boot-starter-webflux`), Spring Boot can also auto-configure a <<features#features.nosql.elasticsearch.connecting-using-reactive-rest,ReactiveElasticsearchClient>> and a `ReactiveElasticsearchTemplate` as beans.
|
||||
They are the reactive equivalent of the other REST clients.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.elasticsearch.repositories]]
|
||||
==== Spring Data Elasticsearch Repositories
|
||||
Spring Data includes repository support for Elasticsearch.
|
||||
As with the JPA repositories discussed earlier, the basic principle is that queries are constructed for you automatically based on method names.
|
||||
|
||||
In fact, both Spring Data JPA and Spring Data Elasticsearch share the same common infrastructure.
|
||||
You could take the JPA example from earlier and, assuming that `City` is now an Elasticsearch `@Document` class rather than a JPA `@Entity`, it works in the same way.
|
||||
|
||||
TIP: For complete details of Spring Data Elasticsearch, refer to the {spring-data-elasticsearch-docs}[reference documentation].
|
||||
|
||||
Spring Boot supports both classic and reactive Elasticsearch repositories, using the `ElasticsearchRestTemplate` or `ReactiveElasticsearchTemplate` beans.
|
||||
Most likely those beans are auto-configured by Spring Boot given the required dependencies are present.
|
||||
|
||||
If you wish to use your own template for backing the Elasticsearch repositories, you can add your own `ElasticsearchRestTemplate` or `ElasticsearchOperations` `@Bean`, as long as it is named `"elasticsearchTemplate"`.
|
||||
Same applies to `ReactiveElasticsearchTemplate` and `ReactiveElasticsearchOperations`, with the bean name `"reactiveElasticsearchTemplate"`.
|
||||
|
||||
You can choose to disable the repositories support with the following property:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
data:
|
||||
elasticsearch:
|
||||
repositories:
|
||||
enabled: false
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.nosql.cassandra]]
|
||||
=== Cassandra
|
||||
https://cassandra.apache.org/[Cassandra] is an open source, distributed database management system designed to handle large amounts of data across many commodity servers.
|
||||
Spring Boot offers auto-configuration for Cassandra and the abstractions on top of it provided by https://github.com/spring-projects/spring-data-cassandra[Spring Data Cassandra].
|
||||
There is a `spring-boot-starter-data-cassandra` "`Starter`" for collecting the dependencies in a convenient way.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.cassandra.connecting]]
|
||||
==== Connecting to Cassandra
|
||||
You can inject an auto-configured `CassandraTemplate` or a Cassandra `CqlSession` instance as you would with any other Spring Bean.
|
||||
The `spring.data.cassandra.*` properties can be used to customize the connection.
|
||||
Generally, you provide `keyspace-name` and `contact-points` as well the local datacenter name, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
data:
|
||||
cassandra:
|
||||
keyspace-name: "mykeyspace"
|
||||
contact-points: "cassandrahost1:9042,cassandrahost2:9042"
|
||||
local-datacenter: "datacenter1"
|
||||
----
|
||||
|
||||
If the port is the same for all your contact points you can use a shortcut and only specify the host names, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
data:
|
||||
cassandra:
|
||||
keyspace-name: "mykeyspace"
|
||||
contact-points: "cassandrahost1,cassandrahost2"
|
||||
local-datacenter: "datacenter1"
|
||||
----
|
||||
|
||||
TIP: Those two examples are identical as the port default to `9042`.
|
||||
If you need to configure the port, use `spring.data.cassandra.port`.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The Cassandra driver has its own configuration infrastructure that loads an `application.conf` at the root of the classpath.
|
||||
|
||||
Spring Boot does not look for such a file by default but can load one using `spring.data.cassandra.config`.
|
||||
If a property is both present in `+spring.data.cassandra.*+` and the configuration file, the value in `+spring.data.cassandra.*+` takes precedence.
|
||||
|
||||
For more advanced driver customizations, you can register an arbitrary number of beans that implement `DriverConfigLoaderBuilderCustomizer`.
|
||||
The `CqlSession` can be customized with a bean of type `CqlSessionBuilderCustomizer`.
|
||||
====
|
||||
|
||||
NOTE: If you're using `CqlSessionBuilder` to create multiple `CqlSession` beans, keep in mind the builder is mutable so make sure to inject a fresh copy for each session.
|
||||
|
||||
The following code listing shows how to inject a Cassandra bean:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/cassandra/template/MyBean.java[]
|
||||
----
|
||||
|
||||
If you add your own `@Bean` of type `CassandraTemplate`, it replaces the default.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.cassandra.repositories]]
|
||||
==== Spring Data Cassandra Repositories
|
||||
Spring Data includes basic repository support for Cassandra.
|
||||
Currently, this is more limited than the JPA repositories discussed earlier and needs to annotate finder methods with `@Query`.
|
||||
|
||||
TIP: For complete details of Spring Data Cassandra, refer to the https://docs.spring.io/spring-data/cassandra/docs/[reference documentation].
|
||||
|
||||
|
||||
|
||||
[[features.nosql.couchbase]]
|
||||
=== Couchbase
|
||||
https://www.couchbase.com/[Couchbase] is an open-source, distributed, multi-model NoSQL document-oriented database that is optimized for interactive applications.
|
||||
Spring Boot offers auto-configuration for Couchbase and the abstractions on top of it provided by https://github.com/spring-projects/spring-data-couchbase[Spring Data Couchbase].
|
||||
There are `spring-boot-starter-data-couchbase` and `spring-boot-starter-data-couchbase-reactive` "`Starters`" for collecting the dependencies in a convenient way.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.couchbase.connecting]]
|
||||
==== Connecting to Couchbase
|
||||
You can get a `Cluster` by adding the Couchbase SDK and some configuration.
|
||||
The `spring.couchbase.*` properties can be used to customize the connection.
|
||||
Generally, you provide the https://github.com/couchbaselabs/sdk-rfcs/blob/master/rfc/0011-connection-string.md[connection string], username, and password, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
couchbase:
|
||||
connection-string: "couchbase://192.168.1.123"
|
||||
username: "user"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
It is also possible to customize some of the `ClusterEnvironment` settings.
|
||||
For instance, the following configuration changes the timeout to use to open a new `Bucket` and enables SSL support:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
couchbase:
|
||||
env:
|
||||
timeouts:
|
||||
connect: "3s"
|
||||
ssl:
|
||||
key-store: "/location/of/keystore.jks"
|
||||
key-store-password: "secret"
|
||||
----
|
||||
|
||||
TIP: Check the `spring.couchbase.env.*` properties for more details.
|
||||
To take more control, one or more `ClusterEnvironmentBuilderCustomizer` beans can be used.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.couchbase.repositories]]
|
||||
==== Spring Data Couchbase Repositories
|
||||
Spring Data includes repository support for Couchbase.
|
||||
For complete details of Spring Data Couchbase, refer to the {spring-data-couchbase-docs}[reference documentation].
|
||||
|
||||
You can inject an auto-configured `CouchbaseTemplate` instance as you would with any other Spring Bean, provided a `CouchbaseClientFactory` bean is available.
|
||||
This happens when a `Cluster` is available, as described above, and a bucket name has been specified:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
data:
|
||||
couchbase:
|
||||
bucket-name: "my-bucket"
|
||||
----
|
||||
|
||||
The following examples shows how to inject a `CouchbaseTemplate` bean:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/couchbase/template/MyBean.java[]
|
||||
----
|
||||
|
||||
There are a few beans that you can define in your own configuration to override those provided by the auto-configuration:
|
||||
|
||||
* A `CouchbaseMappingContext` `@Bean` with a name of `couchbaseMappingContext`.
|
||||
* A `CustomConversions` `@Bean` with a name of `couchbaseCustomConversions`.
|
||||
* A `CouchbaseTemplate` `@Bean` with a name of `couchbaseTemplate`.
|
||||
|
||||
To avoid hard-coding those names in your own config, you can reuse `BeanNames` provided by Spring Data Couchbase.
|
||||
For instance, you can customize the converters to use, as follows:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/couchbase/CouchbaseConversionsConfiguration.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.nosql.ldap]]
|
||||
=== LDAP
|
||||
https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol[LDAP] (Lightweight Directory Access Protocol) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an IP network.
|
||||
Spring Boot offers auto-configuration for any compliant LDAP server as well as support for the embedded in-memory LDAP server from https://ldap.com/unboundid-ldap-sdk-for-java/[UnboundID].
|
||||
|
||||
LDAP abstractions are provided by https://github.com/spring-projects/spring-data-ldap[Spring Data LDAP].
|
||||
There is a `spring-boot-starter-data-ldap` "`Starter`" for collecting the dependencies in a convenient way.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.ldap.connecting]]
|
||||
==== Connecting to an LDAP Server
|
||||
To connect to an LDAP server, make sure you declare a dependency on the `spring-boot-starter-data-ldap` "`Starter`" or `spring-ldap-core` and then declare the URLs of your server in your application.properties, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
ldap:
|
||||
urls: "ldap://myserver:1235"
|
||||
username: "admin"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
If you need to customize connection settings, you can use the `spring.ldap.base` and `spring.ldap.base-environment` properties.
|
||||
|
||||
An `LdapContextSource` is auto-configured based on these settings.
|
||||
If a `DirContextAuthenticationStrategy` bean is available, it is associated to the auto-configured `LdapContextSource`.
|
||||
If you need to customize it, for instance to use a `PooledContextSource`, you can still inject the auto-configured `LdapContextSource`.
|
||||
Make sure to flag your customized `ContextSource` as `@Primary` so that the auto-configured `LdapTemplate` uses it.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.ldap.repositories]]
|
||||
==== Spring Data LDAP Repositories
|
||||
Spring Data includes repository support for LDAP.
|
||||
For complete details of Spring Data LDAP, refer to the https://docs.spring.io/spring-data/ldap/docs/1.0.x/reference/html/[reference documentation].
|
||||
|
||||
You can also inject an auto-configured `LdapTemplate` instance as you would with any other Spring Bean, as shown in the following example:
|
||||
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/nosql/ldap/template/MyBean.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.nosql.ldap.embedded]]
|
||||
==== Embedded In-memory LDAP Server
|
||||
For testing purposes, Spring Boot supports auto-configuration of an in-memory LDAP server from https://ldap.com/unboundid-ldap-sdk-for-java/[UnboundID].
|
||||
To configure the server, add a dependency to `com.unboundid:unboundid-ldapsdk` and declare a configprop:spring.ldap.embedded.base-dn[] property, as follows:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
ldap:
|
||||
embedded:
|
||||
base-dn: "dc=spring,dc=io"
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
It is possible to define multiple base-dn values, however, since distinguished names usually contain commas, they must be defined using the correct notation.
|
||||
|
||||
In yaml files, you can use the yaml list notation. In properties files, you must include the index as part of the property name:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring.ldap.embedded.base-dn:
|
||||
- dc=spring,dc=io
|
||||
- dc=pivotal,dc=io
|
||||
----
|
||||
====
|
||||
|
||||
By default, the server starts on a random port and triggers the regular LDAP support.
|
||||
There is no need to specify a configprop:spring.ldap.urls[] property.
|
||||
|
||||
If there is a `schema.ldif` file on your classpath, it is used to initialize the server.
|
||||
If you want to load the initialization script from a different resource, you can also use the configprop:spring.ldap.embedded.ldif[] property.
|
||||
|
||||
By default, a standard schema is used to validate `LDIF` files.
|
||||
You can turn off validation altogether by setting the configprop:spring.ldap.embedded.validation.enabled[] property.
|
||||
If you have custom attributes, you can use configprop:spring.ldap.embedded.validation.schema[] to define your custom attribute types or object classes.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.influxdb]]
|
||||
=== InfluxDB
|
||||
https://www.influxdata.com/[InfluxDB] is an open-source time series database optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet-of-Things sensor data, and real-time analytics.
|
||||
|
||||
|
||||
|
||||
[[features.nosql.influxdb.connecting]]
|
||||
==== Connecting to InfluxDB
|
||||
Spring Boot auto-configures an `InfluxDB` instance, provided the `influxdb-java` client is on the classpath and the URL of the database is set, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
influx:
|
||||
url: "https://172.0.0.1:8086"
|
||||
----
|
||||
|
||||
If the connection to InfluxDB requires a user and password, you can set the `spring.influx.user` and `spring.influx.password` properties accordingly.
|
||||
|
||||
InfluxDB relies on OkHttp.
|
||||
If you need to tune the http client `InfluxDB` uses behind the scenes, you can register an `InfluxDbOkHttpClientBuilderProvider` bean.
|
||||
|
||||
If you need more control over the configuration, consider registering an `InfluxDbCustomizer` bean.
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
[[features.profiles]]
|
||||
== Profiles
|
||||
Spring Profiles provide a way to segregate parts of your application configuration and make it be available only in certain environments.
|
||||
Any `@Component`, `@Configuration` or `@ConfigurationProperties` can be marked with `@Profile` to limit when it is loaded, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/profiles/ProductionConfiguration.java[]
|
||||
----
|
||||
|
||||
NOTE: If `@ConfigurationProperties` beans are registered via `@EnableConfigurationProperties` instead of automatic scanning, the `@Profile` annotation needs to be specified on the `@Configuration` class that has the `@EnableConfigurationProperties` annotation.
|
||||
In the case where `@ConfigurationProperties` are scanned, `@Profile` can be specified on the `@ConfigurationProperties` class itself.
|
||||
|
||||
You can use a configprop:spring.profiles.active[] `Environment` property to specify which profiles are active.
|
||||
You can specify the property in any of the ways described earlier in this chapter.
|
||||
For example, you could include it in your `application.properties`, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
profiles:
|
||||
active: "dev,hsqldb"
|
||||
----
|
||||
|
||||
You could also specify it on the command line by using the following switch: `--spring.profiles.active=dev,hsqldb`.
|
||||
|
||||
|
||||
|
||||
[[features.profiles.adding-active-profiles]]
|
||||
=== Adding Active Profiles
|
||||
The configprop:spring.profiles.active[] property follows the same ordering rules as other properties: The highest `PropertySource` wins.
|
||||
This means that you can specify active profiles in `application.properties` and then *replace* them by using the command line switch.
|
||||
|
||||
Sometimes, it is useful to have properties that *add* to the active profiles rather than replace them.
|
||||
The `SpringApplication` entry point has a Java API for setting additional profiles (that is, on top of those activated by the configprop:spring.profiles.active[] property).
|
||||
See the `setAdditionalProfiles()` method in {spring-boot-module-api}/SpringApplication.html[SpringApplication].
|
||||
Profile groups, which are described in the <<features#features.profiles.groups,next section>> can also be used to add active profiles if a given profile is active.
|
||||
|
||||
|
||||
|
||||
[[features.profiles.groups]]
|
||||
=== Profile Groups
|
||||
Occasionally the profiles that you define and use in your application are too fine-grained and become cumbersome to use.
|
||||
For example, you might have `proddb` and `prodmq` profiles that you use to enable database and messaging features independently.
|
||||
|
||||
To help with this, Spring Boot lets you define profile groups.
|
||||
A profile group allows you to define a logical name for a related group of profiles.
|
||||
|
||||
For example, we can create a `production` group that consists of our `proddb` and `prodmq` profiles.
|
||||
|
||||
[source,yaml,indent=0,configblocks]
|
||||
----
|
||||
spring:
|
||||
profiles:
|
||||
group:
|
||||
production:
|
||||
- "proddb"
|
||||
- "prodmq"
|
||||
----
|
||||
|
||||
Our application can now be started using `--spring.profiles.active=production` to active the `production`, `proddb` and `prodmq` profiles in one hit.
|
||||
|
||||
|
||||
|
||||
[[features.profiles.programmatically-setting-profiles]]
|
||||
=== Programmatically Setting Profiles
|
||||
You can programmatically set active profiles by calling `SpringApplication.setAdditionalProfiles(...)` before your application runs.
|
||||
It is also possible to activate profiles by using Spring's `ConfigurableEnvironment` interface.
|
||||
|
||||
|
||||
|
||||
[[features.profiles.profile-specific-configuration-files]]
|
||||
=== Profile-specific Configuration Files
|
||||
Profile-specific variants of both `application.properties` (or `application.yml`) and files referenced through `@ConfigurationProperties` are considered as files and loaded.
|
||||
See "<<features#features.external-config.files.profile-specific>>" for details.
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
[[features.quartz]]
|
||||
== Quartz Scheduler
|
||||
Spring Boot offers several conveniences for working with the https://www.quartz-scheduler.org/[Quartz scheduler], including the `spring-boot-starter-quartz` "`Starter`".
|
||||
If Quartz is available, a `Scheduler` is auto-configured (through the `SchedulerFactoryBean` abstraction).
|
||||
|
||||
Beans of the following types are automatically picked up and associated with the `Scheduler`:
|
||||
|
||||
* `JobDetail`: defines a particular Job.
|
||||
`JobDetail` instances can be built with the `JobBuilder` API.
|
||||
* `Calendar`.
|
||||
* `Trigger`: defines when a particular job is triggered.
|
||||
|
||||
By default, an in-memory `JobStore` is used.
|
||||
However, it is possible to configure a JDBC-based store if a `DataSource` bean is available in your application and if the configprop:spring.quartz.job-store-type[] property is configured accordingly, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
quartz:
|
||||
job-store-type: "jdbc"
|
||||
----
|
||||
|
||||
When the JDBC store is used, the schema can be initialized on startup, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
quartz:
|
||||
jdbc:
|
||||
initialize-schema: "always"
|
||||
----
|
||||
|
||||
WARNING: By default, the database is detected and initialized by using the standard scripts provided with the Quartz library.
|
||||
These scripts drop existing tables, deleting all triggers on every restart.
|
||||
It is also possible to provide a custom script by setting the configprop:spring.quartz.jdbc.schema[] property.
|
||||
|
||||
To have Quartz use a `DataSource` other than the application's main `DataSource`, declare a `DataSource` bean, annotating its `@Bean` method with `@QuartzDataSource`.
|
||||
Doing so ensures that the Quartz-specific `DataSource` is used by both the `SchedulerFactoryBean` and for schema initialization.
|
||||
Similarly, to have Quartz use a `TransactionManager` other than the application's main `TransactionManager` declare a `TransactionManager` bean, annotating its `@Bean` method with `@QuartzTransactionManager`.
|
||||
|
||||
By default, jobs created by configuration will not overwrite already registered jobs that have been read from a persistent job store.
|
||||
To enable overwriting existing job definitions set the configprop:spring.quartz.overwrite-existing-jobs[] property.
|
||||
|
||||
Quartz Scheduler configuration can be customized using `spring.quartz` properties and `SchedulerFactoryBeanCustomizer` beans, which allow programmatic `SchedulerFactoryBean` customization.
|
||||
Advanced Quartz configuration properties can be customized using `spring.quartz.properties.*`.
|
||||
|
||||
NOTE: In particular, an `Executor` bean is not associated with the scheduler as Quartz offers a way to configure the scheduler via `spring.quartz.properties`.
|
||||
If you need to customize the task executor, consider implementing `SchedulerFactoryBeanCustomizer`.
|
||||
|
||||
Jobs can define setters to inject data map properties.
|
||||
Regular beans can also be injected in a similar manner, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/quartz/SampleJob.java[]
|
||||
----
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
[[features.resttemplate]]
|
||||
== Calling REST Services with RestTemplate
|
||||
If you need to call remote REST services from your application, you can use the Spring Framework's {spring-framework-api}/web/client/RestTemplate.html[`RestTemplate`] class.
|
||||
Since `RestTemplate` instances often need to be customized before being used, Spring Boot does not provide any single auto-configured `RestTemplate` bean.
|
||||
It does, however, auto-configure a `RestTemplateBuilder`, which can be used to create `RestTemplate` instances when needed.
|
||||
The auto-configured `RestTemplateBuilder` ensures that sensible `HttpMessageConverters` are applied to `RestTemplate` instances.
|
||||
|
||||
The following code shows a typical example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/resttemplate/MyService.java[]
|
||||
----
|
||||
|
||||
TIP: `RestTemplateBuilder` includes a number of useful methods that can be used to quickly configure a `RestTemplate`.
|
||||
For example, to add BASIC auth support, you can use `builder.basicAuthentication("user", "password").build()`.
|
||||
|
||||
|
||||
|
||||
[[features.resttemplate.customization]]
|
||||
=== RestTemplate Customization
|
||||
There are three main approaches to `RestTemplate` customization, depending on how broadly you want the customizations to apply.
|
||||
|
||||
To make the scope of any customizations as narrow as possible, inject the auto-configured `RestTemplateBuilder` and then call its methods as required.
|
||||
Each method call returns a new `RestTemplateBuilder` instance, so the customizations only affect this use of the builder.
|
||||
|
||||
To make an application-wide, additive customization, use a `RestTemplateCustomizer` bean.
|
||||
All such beans are automatically registered with the auto-configured `RestTemplateBuilder` and are applied to any templates that are built with it.
|
||||
|
||||
The following example shows a customizer that configures the use of a proxy for all hosts except `192.168.0.5`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/resttemplate/RestTemplateProxyCustomizer.java[]
|
||||
----
|
||||
|
||||
Finally, you can also create your own `RestTemplateBuilder` bean.
|
||||
To prevent switching off the auto-configuration of a `RestTemplateBuilder` and prevent any `RestTemplateCustomizer` beans from being used, make sure to configure your custom instance with a `RestTemplateBuilderConfigurer`.
|
||||
The following example exposes a `RestTemplateBuilder` with what Spring Boot would auto-configure, except that custom connect and read timeouts are also specified:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/resttemplate/RestTemplateBuilderConfiguration.java[]
|
||||
----
|
||||
|
||||
The most extreme (and rarely used) option is to create your own `RestTemplateBuilder` bean without using a configurer.
|
||||
Doing so switches off the auto-configuration of a `RestTemplateBuilder` and prevents any `RestTemplateCustomizer` beans from being used.
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
[[features.rsocket]]
|
||||
== RSocket
|
||||
https://rsocket.io[RSocket] is a binary protocol for use on byte stream transports.
|
||||
It enables symmetric interaction models via async message passing over a single connection.
|
||||
|
||||
|
||||
The `spring-messaging` module of the Spring Framework provides support for RSocket requesters and responders, both on the client and on the server side.
|
||||
See the {spring-framework-docs}/web-reactive.html#rsocket-spring[RSocket section] of the Spring Framework reference for more details, including an overview of the RSocket protocol.
|
||||
|
||||
|
||||
|
||||
[[features.rsocket.strategies-auto-configuration]]
|
||||
=== RSocket Strategies Auto-configuration
|
||||
Spring Boot auto-configures an `RSocketStrategies` bean that provides all the required infrastructure for encoding and decoding RSocket payloads.
|
||||
By default, the auto-configuration will try to configure the following (in order):
|
||||
|
||||
. https://cbor.io/[CBOR] codecs with Jackson
|
||||
. JSON codecs with Jackson
|
||||
|
||||
The `spring-boot-starter-rsocket` starter provides both dependencies.
|
||||
Check out the <<features#features.json.jackson,Jackson support section>> to know more about customization possibilities.
|
||||
|
||||
Developers can customize the `RSocketStrategies` component by creating beans that implement the `RSocketStrategiesCustomizer` interface.
|
||||
Note that their `@Order` is important, as it determines the order of codecs.
|
||||
|
||||
|
||||
|
||||
[[features.rsocket.server-auto-configuration]]
|
||||
=== RSocket server Auto-configuration
|
||||
Spring Boot provides RSocket server auto-configuration.
|
||||
The required dependencies are provided by the `spring-boot-starter-rsocket`.
|
||||
|
||||
Spring Boot allows exposing RSocket over WebSocket from a WebFlux server, or standing up an independent RSocket server.
|
||||
This depends on the type of application and its configuration.
|
||||
|
||||
For WebFlux application (i.e. of type `WebApplicationType.REACTIVE`), the RSocket server will be plugged into the Web Server only if the following properties match:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rsocket:
|
||||
server:
|
||||
mapping-path: "/rsocket"
|
||||
transport: "websocket"
|
||||
----
|
||||
|
||||
WARNING: Plugging RSocket into a web server is only supported with Reactor Netty, as RSocket itself is built with that library.
|
||||
|
||||
Alternatively, an RSocket TCP or websocket server is started as an independent, embedded server.
|
||||
Besides the dependency requirements, the only required configuration is to define a port for that server:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rsocket:
|
||||
server:
|
||||
port: 9898
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.rsocket.messaging]]
|
||||
=== Spring Messaging RSocket support
|
||||
Spring Boot will auto-configure the Spring Messaging infrastructure for RSocket.
|
||||
|
||||
This means that Spring Boot will create a `RSocketMessageHandler` bean that will handle RSocket requests to your application.
|
||||
|
||||
|
||||
|
||||
[[features.rsocket.requester]]
|
||||
=== Calling RSocket Services with RSocketRequester
|
||||
Once the `RSocket` channel is established between server and client, any party can send or receive requests to the other.
|
||||
|
||||
As a server, you can get injected with an `RSocketRequester` instance on any handler method of an RSocket `@Controller`.
|
||||
As a client, you need to configure and establish an RSocket connection first.
|
||||
Spring Boot auto-configures an `RSocketRequester.Builder` for such cases with the expected codecs.
|
||||
|
||||
The `RSocketRequester.Builder` instance is a prototype bean, meaning each injection point will provide you with a new instance .
|
||||
This is done on purpose since this builder is stateful and you shouldn't create requesters with different setups using the same instance.
|
||||
|
||||
The following code shows a typical example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/rsocket/MyService.java[]
|
||||
----
|
||||
|
|
@ -0,0 +1,313 @@
|
|||
[[features.security]]
|
||||
== Security
|
||||
If {spring-security}[Spring Security] is on the classpath, then web applications are secured by default.
|
||||
Spring Boot relies on Spring Security’s content-negotiation strategy to determine whether to use `httpBasic` or `formLogin`.
|
||||
To add method-level security to a web application, you can also add `@EnableGlobalMethodSecurity` with your desired settings.
|
||||
Additional information can be found in the {spring-security-docs}#jc-method[Spring Security Reference Guide].
|
||||
|
||||
The default `UserDetailsService` has a single user.
|
||||
The user name is `user`, and the password is random and is printed at INFO level when the application starts, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
Using generated security password: 78fa095d-3f4c-48b1-ad50-e24c31d5cf35
|
||||
----
|
||||
|
||||
NOTE: If you fine-tune your logging configuration, ensure that the `org.springframework.boot.autoconfigure.security` category is set to log `INFO`-level messages.
|
||||
Otherwise, the default password is not printed.
|
||||
|
||||
You can change the username and password by providing a `spring.security.user.name` and `spring.security.user.password`.
|
||||
|
||||
The basic features you get by default in a web application are:
|
||||
|
||||
* A `UserDetailsService` (or `ReactiveUserDetailsService` in case of a WebFlux application) bean with in-memory store and a single user with a generated password (see {spring-boot-module-api}/autoconfigure/security/SecurityProperties.User.html[`SecurityProperties.User`] for the properties of the user).
|
||||
* Form-based login or HTTP Basic security (depending on the `Accept` header in the request) for the entire application (including actuator endpoints if actuator is on the classpath).
|
||||
* A `DefaultAuthenticationEventPublisher` for publishing authentication events.
|
||||
|
||||
You can provide a different `AuthenticationEventPublisher` by adding a bean for it.
|
||||
|
||||
|
||||
|
||||
[[features.security.spring-mvc]]
|
||||
=== MVC Security
|
||||
The default security configuration is implemented in `SecurityAutoConfiguration` and `UserDetailsServiceAutoConfiguration`.
|
||||
`SecurityAutoConfiguration` imports `SpringBootWebSecurityConfiguration` for web security and `UserDetailsServiceAutoConfiguration` configures authentication, which is also relevant in non-web applications.
|
||||
To switch off the default web application security configuration completely or to combine multiple Spring Security components such as OAuth2 Client and Resource Server, add a bean of type `SecurityFilterChain` (doing so does not disable the `UserDetailsService` configuration or Actuator's security).
|
||||
|
||||
To also switch off the `UserDetailsService` configuration, you can add a bean of type `UserDetailsService`, `AuthenticationProvider`, or `AuthenticationManager`.
|
||||
|
||||
Access rules can be overridden by adding a custom `SecurityFilterChain` or `WebSecurityConfigurerAdapter` bean.
|
||||
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
|
||||
`EndpointRequest` can be used to create a `RequestMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
|
||||
`PathRequest` can be used to create a `RequestMatcher` for resources in commonly used locations.
|
||||
|
||||
|
||||
|
||||
[[features.security.spring-webflux]]
|
||||
=== WebFlux Security
|
||||
Similar to Spring MVC applications, you can secure your WebFlux applications by adding the `spring-boot-starter-security` dependency.
|
||||
The default security configuration is implemented in `ReactiveSecurityAutoConfiguration` and `UserDetailsServiceAutoConfiguration`.
|
||||
`ReactiveSecurityAutoConfiguration` imports `WebFluxSecurityConfiguration` for web security and `UserDetailsServiceAutoConfiguration` configures authentication, which is also relevant in non-web applications.
|
||||
To switch off the default web application security configuration completely, you can add a bean of type `WebFilterChainProxy` (doing so does not disable the `UserDetailsService` configuration or Actuator's security).
|
||||
|
||||
To also switch off the `UserDetailsService` configuration, you can add a bean of type `ReactiveUserDetailsService` or `ReactiveAuthenticationManager`.
|
||||
|
||||
Access rules and the use of multiple Spring Security components such as OAuth 2 Client and Resource Server can be configured by adding a custom `SecurityWebFilterChain` bean.
|
||||
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
|
||||
`EndpointRequest` can be used to create a `ServerWebExchangeMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
|
||||
|
||||
`PathRequest` can be used to create a `ServerWebExchangeMatcher` for resources in commonly used locations.
|
||||
|
||||
For example, you can customize your security configuration by adding something like:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/security/CustomWebFluxSecurityConfiguration.java[]
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.security.oauth2]]
|
||||
=== OAuth2
|
||||
https://oauth.net/2/[OAuth2] is a widely used authorization framework that is supported by Spring.
|
||||
|
||||
|
||||
|
||||
[[features.security.oauth2.client]]
|
||||
==== Client
|
||||
If you have `spring-security-oauth2-client` on your classpath, you can take advantage of some auto-configuration to set up an OAuth2/Open ID Connect clients.
|
||||
This configuration makes use of the properties under `OAuth2ClientProperties`.
|
||||
The same properties are applicable to both servlet and reactive applications.
|
||||
|
||||
You can register multiple OAuth2 clients and providers under the `spring.security.oauth2.client` prefix, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
security:
|
||||
oauth2:
|
||||
client:
|
||||
registration:
|
||||
my-client-1:
|
||||
client-id: "abcd"
|
||||
client-secret: "password"
|
||||
client-name: "Client for user scope"
|
||||
provider: "my-oauth-provider"
|
||||
scope: "user"
|
||||
redirect-uri: "https://my-redirect-uri.com"
|
||||
client-authentication-method: "basic"
|
||||
authorization-grant-type: "authorization-code"
|
||||
|
||||
my-client-2:
|
||||
client-id: "abcd"
|
||||
client-secret: "password"
|
||||
client-name: "Client for email scope"
|
||||
provider: "my-oauth-provider"
|
||||
scope: "email"
|
||||
redirect-uri: "https://my-redirect-uri.com"
|
||||
client-authentication-method: "basic"
|
||||
authorization-grant-type: "authorization_code"
|
||||
|
||||
provider:
|
||||
my-oauth-provider:
|
||||
authorization-uri: "https://my-auth-server/oauth/authorize"
|
||||
token-uri: "https://my-auth-server/oauth/token"
|
||||
user-info-uri: "https://my-auth-server/userinfo"
|
||||
user-info-authentication-method: "header"
|
||||
jwk-set-uri: "https://my-auth-server/token_keys"
|
||||
user-name-attribute: "name"
|
||||
----
|
||||
|
||||
For OpenID Connect providers that support https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect discovery], the configuration can be further simplified.
|
||||
The provider needs to be configured with an `issuer-uri` which is the URI that the it asserts as its Issuer Identifier.
|
||||
For example, if the `issuer-uri` provided is "https://example.com", then an `OpenID Provider Configuration Request` will be made to "https://example.com/.well-known/openid-configuration".
|
||||
The result is expected to be an `OpenID Provider Configuration Response`.
|
||||
The following example shows how an OpenID Connect Provider can be configured with the `issuer-uri`:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
security:
|
||||
oauth2:
|
||||
client:
|
||||
provider:
|
||||
oidc-provider:
|
||||
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
|
||||
----
|
||||
|
||||
By default, Spring Security's `OAuth2LoginAuthenticationFilter` only processes URLs matching `/login/oauth2/code/*`.
|
||||
If you want to customize the `redirect-uri` to use a different pattern, you need to provide configuration to process that custom pattern.
|
||||
For example, for servlet applications, you can add your own `SecurityFilterChain` that resembles the following:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/security/OAuthClientConfiguration.java[]
|
||||
----
|
||||
|
||||
TIP: Spring Boot auto-configures an `InMemoryOAuth2AuthorizedClientService` which is used by Spring Security for the management of client registrations.
|
||||
The `InMemoryOAuth2AuthorizedClientService` has limited capabilities and we recommend using it only for development environments.
|
||||
For production environments, consider using a `JdbcOAuth2AuthorizedClientService` or creating your own implementation of `OAuth2AuthorizedClientService`.
|
||||
|
||||
|
||||
|
||||
[[features.security.oauth2.client.common-providers]]
|
||||
===== OAuth2 client registration for common providers
|
||||
For common OAuth2 and OpenID providers, including Google, Github, Facebook, and Okta, we provide a set of provider defaults (`google`, `github`, `facebook`, and `okta`, respectively).
|
||||
|
||||
If you do not need to customize these providers, you can set the `provider` attribute to the one for which you need to infer defaults.
|
||||
Also, if the key for the client registration matches a default supported provider, Spring Boot infers that as well.
|
||||
|
||||
In other words, the two configurations in the following example use the Google provider:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
security:
|
||||
oauth2:
|
||||
client:
|
||||
registration:
|
||||
my-client:
|
||||
client-id: "abcd"
|
||||
client-secret: "password"
|
||||
provider: "google"
|
||||
google:
|
||||
client-id: "abcd"
|
||||
client-secret: "password"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.security.oauth2.server]]
|
||||
==== Resource Server
|
||||
If you have `spring-security-oauth2-resource-server` on your classpath, Spring Boot can set up an OAuth2 Resource Server.
|
||||
For JWT configuration, a JWK Set URI or OIDC Issuer URI needs to be specified, as shown in the following examples:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
security:
|
||||
oauth2:
|
||||
resourceserver:
|
||||
jwt:
|
||||
jwk-set-uri: "https://example.com/oauth2/default/v1/keys"
|
||||
----
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
security:
|
||||
oauth2:
|
||||
resourceserver:
|
||||
jwt:
|
||||
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
|
||||
----
|
||||
|
||||
NOTE: If the authorization server does not support a JWK Set URI, you can configure the resource server with the Public Key used for verifying the signature of the JWT.
|
||||
This can be done using the configprop:spring.security.oauth2.resourceserver.jwt.public-key-location[] property, where the value needs to point to a file containing the public key in the PEM-encoded x509 format.
|
||||
|
||||
The same properties are applicable for both servlet and reactive applications.
|
||||
|
||||
Alternatively, you can define your own `JwtDecoder` bean for servlet applications or a `ReactiveJwtDecoder` for reactive applications.
|
||||
|
||||
In cases where opaque tokens are used instead of JWTs, you can configure the following properties to validate tokens via introspection:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
security:
|
||||
oauth2:
|
||||
resourceserver:
|
||||
opaquetoken:
|
||||
introspection-uri: "https://example.com/check-token"
|
||||
client-id: "my-client-id"
|
||||
client-secret: "my-client-secret"
|
||||
----
|
||||
|
||||
Again, the same properties are applicable for both servlet and reactive applications.
|
||||
|
||||
Alternatively, you can define your own `OpaqueTokenIntrospector` bean for servlet applications or a `ReactiveOpaqueTokenIntrospector` for reactive applications.
|
||||
|
||||
|
||||
|
||||
[[features.security.oauth2.authorization-server]]
|
||||
==== Authorization Server
|
||||
Currently, Spring Security does not provide support for implementing an OAuth 2.0 Authorization Server.
|
||||
However, this functionality is available from the {spring-security-oauth2}[Spring Security OAuth] project, which will eventually be superseded by Spring Security completely.
|
||||
Until then, you can use the `spring-security-oauth2-autoconfigure` module to easily set up an OAuth 2.0 authorization server; see its https://docs.spring.io/spring-security-oauth2-boot/[documentation] for instructions.
|
||||
|
||||
|
||||
|
||||
[[features.security.saml2]]
|
||||
=== SAML 2.0
|
||||
|
||||
|
||||
|
||||
[[features.security.saml2.relying-party]]
|
||||
==== Relying Party
|
||||
If you have `spring-security-saml2-service-provider` on your classpath, you can take advantage of some auto-configuration to set up a SAML 2.0 Relying Party.
|
||||
This configuration makes use of the properties under `Saml2RelyingPartyProperties`.
|
||||
|
||||
A relying party registration represents a paired configuration between an Identity Provider, IDP, and a Service Provider, SP.
|
||||
You can register multiple relying parties under the `spring.security.saml2.relyingparty` prefix, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
security:
|
||||
saml2:
|
||||
relyingparty:
|
||||
registration:
|
||||
my-relying-party1:
|
||||
signing:
|
||||
credentials:
|
||||
- private-key-location: "path-to-private-key"
|
||||
certificate-location: "path-to-certificate"
|
||||
decryption:
|
||||
credentials:
|
||||
- private-key-location: "path-to-private-key"
|
||||
certificate-location: "path-to-certificate"
|
||||
identityprovider:
|
||||
verification:
|
||||
credentials:
|
||||
- certificate-location: "path-to-verification-cert"
|
||||
entity-id: "remote-idp-entity-id1"
|
||||
sso-url: "https://remoteidp1.sso.url"
|
||||
my-relying-party2:
|
||||
signing:
|
||||
credentials:
|
||||
- private-key-location: "path-to-private-key"
|
||||
certificate-location: "path-to-certificate"
|
||||
decryption:
|
||||
credentials:
|
||||
- private-key-location: "path-to-private-key"
|
||||
certificate-location: "path-to-certificate"
|
||||
identityprovider:
|
||||
verification:
|
||||
credentials:
|
||||
- certificate-location: "path-to-other-verification-cert"
|
||||
entity-id: "remote-idp-entity-id2"
|
||||
sso-url: "https://remoteidp2.sso.url"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.security.actuator]]
|
||||
=== Actuator Security
|
||||
For security purposes, all actuators other than `/health` are disabled by default.
|
||||
The configprop:management.endpoints.web.exposure.include[] property can be used to enable the actuators.
|
||||
|
||||
If Spring Security is on the classpath and no other `WebSecurityConfigurerAdapter` or `SecurityFilterChain` bean is present, all actuators other than `/health` are secured by Spring Boot auto-configuration.
|
||||
If you define a custom `WebSecurityConfigurerAdapter` or `SecurityFilterChain` bean, Spring Boot auto-configuration will back off and you will be in full control of actuator access rules.
|
||||
|
||||
NOTE: Before setting the `management.endpoints.web.exposure.include`, ensure that the exposed actuators do not contain sensitive information and/or are secured by placing them behind a firewall or by something like Spring Security.
|
||||
|
||||
|
||||
|
||||
[[features.security.actuator.csrf]]
|
||||
==== Cross Site Request Forgery Protection
|
||||
Since Spring Boot relies on Spring Security's defaults, CSRF protection is turned on by default.
|
||||
This means that the actuator endpoints that require a `POST` (shutdown and loggers endpoints), `PUT` or `DELETE` will get a 403 forbidden error when the default security configuration is in use.
|
||||
|
||||
NOTE: We recommend disabling CSRF protection completely only if you are creating a service that is used by non-browser clients.
|
||||
|
||||
Additional information about CSRF protection can be found in the {spring-security-docs}#csrf[Spring Security Reference Guide].
|
||||
|
|
@ -0,0 +1,420 @@
|
|||
[[features.spring-application]]
|
||||
== SpringApplication
|
||||
The `SpringApplication` class provides a convenient way to bootstrap a Spring application that is started from a `main()` method.
|
||||
In many situations, you can delegate to the static `SpringApplication.run` method, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/main/run/MyApplication.java[]
|
||||
----
|
||||
|
||||
When your application starts, you should see something similar to the following output:
|
||||
|
||||
[indent=0,subs="attributes"]
|
||||
----
|
||||
. ____ _ __ _ _
|
||||
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
|
||||
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
|
||||
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
|
||||
' |____| .__|_| |_|_| |_\__, | / / / /
|
||||
=========|_|==============|___/=/_/_/_/
|
||||
:: Spring Boot :: v{spring-boot-version}
|
||||
|
||||
2021-02-03 10:33:25.224 INFO 17321 --- [ main] o.s.b.d.s.s.SpringAppplicationExample : Starting SpringAppplicationExample using Java 1.8.0_232 on mycomputer with PID 17321 (/apps/myjar.jar started by pwebb)
|
||||
2021-02-03 10:33:25.226 INFO 17900 --- [ main] o.s.b.d.s.s.SpringAppplicationExample : No active profile set, falling back to default profiles: default
|
||||
2021-02-03 10:33:26.046 INFO 17321 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http)
|
||||
2021-02-03 10:33:26.054 INFO 17900 --- [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
|
||||
2021-02-03 10:33:26.055 INFO 17900 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/9.0.41]
|
||||
2021-02-03 10:33:26.097 INFO 17900 --- [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
|
||||
2021-02-03 10:33:26.097 INFO 17900 --- [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 821 ms
|
||||
2021-02-03 10:33:26.144 INFO 17900 --- [ main] s.tomcat.SampleTomcatApplication : ServletContext initialized
|
||||
2021-02-03 10:33:26.376 INFO 17900 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path ''
|
||||
2021-02-03 10:33:26.384 INFO 17900 --- [ main] o.s.b.d.s.s.SpringAppplicationExample : Started SampleTomcatApplication in 1.514 seconds (JVM running for 1.823)
|
||||
----
|
||||
|
||||
|
||||
|
||||
By default, `INFO` logging messages are shown, including some relevant startup details, such as the user that launched the application.
|
||||
If you need a log level other than `INFO`, you can set it, as described in <<features#features.logging.log-levels>>.
|
||||
The application version is determined using the implementation version from the main application class's package.
|
||||
Startup information logging can be turned off by setting `spring.main.log-startup-info` to `false`.
|
||||
This will also turn off logging of the application's active profiles.
|
||||
|
||||
TIP: To add additional logging during startup, you can override `logStartupInfo(boolean)` in a subclass of `SpringApplication`.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.startup-failure]]
|
||||
=== Startup Failure
|
||||
If your application fails to start, registered `FailureAnalyzers` get a chance to provide a dedicated error message and a concrete action to fix the problem.
|
||||
For instance, if you start a web application on port `8080` and that port is already in use, you should see something similar to the following message:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
***************************
|
||||
APPLICATION FAILED TO START
|
||||
***************************
|
||||
|
||||
Description:
|
||||
|
||||
Embedded servlet container failed to start. Port 8080 was already in use.
|
||||
|
||||
Action:
|
||||
|
||||
Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.
|
||||
----
|
||||
|
||||
NOTE: Spring Boot provides numerous `FailureAnalyzer` implementations, and you can <<howto#howto.application.failure-analyzer,add your own>>.
|
||||
|
||||
If no failure analyzers are able to handle the exception, you can still display the full conditions report to better understand what went wrong.
|
||||
To do so, you need to <<features#features.external-config,enable the `debug` property>> or <<features#features.logging.log-levels,enable `DEBUG` logging>> for `org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener`.
|
||||
|
||||
For instance, if you are running your application by using `java -jar`, you can enable the `debug` property as follows:
|
||||
|
||||
[indent=0,subs="attributes"]
|
||||
----
|
||||
$ java -jar myproject-0.0.1-SNAPSHOT.jar --debug
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.lazy-initialization]]
|
||||
=== Lazy Initialization
|
||||
`SpringApplication` allows an application to be initialized lazily.
|
||||
When lazy initialization is enabled, beans are created as they are needed rather than during application startup.
|
||||
As a result, enabling lazy initialization can reduce the time that it takes your application to start.
|
||||
In a web application, enabling lazy initialization will result in many web-related beans not being initialized until an HTTP request is received.
|
||||
|
||||
A downside of lazy initialization is that it can delay the discovery of a problem with the application.
|
||||
If a misconfigured bean is initialized lazily, a failure will no longer occur during startup and the problem will only become apparent when the bean is initialized.
|
||||
Care must also be taken to ensure that the JVM has sufficient memory to accommodate all of the application's beans and not just those that are initialized during startup.
|
||||
For these reasons, lazy initialization is not enabled by default and it is recommended that fine-tuning of the JVM's heap size is done before enabling lazy initialization.
|
||||
|
||||
Lazy initialization can be enabled programmatically using the `lazyInitialization` method on `SpringApplicationBuilder` or the `setLazyInitialization` method on `SpringApplication`.
|
||||
Alternatively, it can be enabled using the configprop:spring.main.lazy-initialization[] property as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
main:
|
||||
lazy-initialization: true
|
||||
----
|
||||
|
||||
TIP: If you want to disable lazy initialization for certain beans while using lazy initialization for the rest of the application, you can explicitly set their lazy attribute to false using the `@Lazy(false)` annotation.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.banner]]
|
||||
=== Customizing the Banner
|
||||
The banner that is printed on start up can be changed by adding a `banner.txt` file to your classpath or by setting the configprop:spring.banner.location[] property to the location of such a file.
|
||||
If the file has an encoding other than UTF-8, you can set `spring.banner.charset`.
|
||||
In addition to a text file, you can also add a `banner.gif`, `banner.jpg`, or `banner.png` image file to your classpath or set the configprop:spring.banner.image.location[] property.
|
||||
Images are converted into an ASCII art representation and printed above any text banner.
|
||||
|
||||
Inside your `banner.txt` file, you can use any of the following placeholders:
|
||||
|
||||
.Banner variables
|
||||
|===
|
||||
| Variable | Description
|
||||
|
||||
| `${application.version}`
|
||||
| The version number of your application, as declared in `MANIFEST.MF`.
|
||||
For example, `Implementation-Version: 1.0` is printed as `1.0`.
|
||||
|
||||
| `${application.formatted-version}`
|
||||
| The version number of your application, as declared in `MANIFEST.MF` and formatted for display (surrounded with brackets and prefixed with `v`).
|
||||
For example `(v1.0)`.
|
||||
|
||||
| `${spring-boot.version}`
|
||||
| The Spring Boot version that you are using.
|
||||
For example `{spring-boot-version}`.
|
||||
|
||||
| `${spring-boot.formatted-version}`
|
||||
| The Spring Boot version that you are using, formatted for display (surrounded with brackets and prefixed with `v`).
|
||||
For example `(v{spring-boot-version})`.
|
||||
|
||||
| `${Ansi.NAME}` (or `${AnsiColor.NAME}`, `${AnsiBackground.NAME}`, `${AnsiStyle.NAME}`)
|
||||
| Where `NAME` is the name of an ANSI escape code.
|
||||
See {spring-boot-module-code}/ansi/AnsiPropertySource.java[`AnsiPropertySource`] for details.
|
||||
|
||||
| `${application.title}`
|
||||
| The title of your application, as declared in `MANIFEST.MF`.
|
||||
For example `Implementation-Title: MyApp` is printed as `MyApp`.
|
||||
|===
|
||||
|
||||
TIP: The `SpringApplication.setBanner(...)` method can be used if you want to generate a banner programmatically.
|
||||
Use the `org.springframework.boot.Banner` interface and implement your own `printBanner()` method.
|
||||
|
||||
You can also use the configprop:spring.main.banner-mode[] property to determine if the banner has to be printed on `System.out` (`console`), sent to the configured logger (`log`), or not produced at all (`off`).
|
||||
|
||||
The printed banner is registered as a singleton bean under the following name: `springBootBanner`.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The `${application.version}` and `${application.formatted-version}` properties are only available if you are using Spring Boot launchers.
|
||||
The values won't be resolved if you are running an unpacked jar and starting it with `java -cp <classpath> <mainclass>`.
|
||||
|
||||
This is why we recommend that you always launch unpacked jars using `java org.springframework.boot.loader.JarLauncher`.
|
||||
This will initialize the `application.*` banner variables before building the classpath and launching your app.
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.customizing-spring-application]]
|
||||
=== Customizing SpringApplication
|
||||
If the `SpringApplication` defaults are not to your taste, you can instead create a local instance and customize it.
|
||||
For example, to turn off the banner, you could write:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/main/custom/MyApplication.java[]
|
||||
----
|
||||
|
||||
NOTE: The constructor arguments passed to `SpringApplication` are configuration sources for Spring beans.
|
||||
In most cases, these are references to `@Configuration` classes, but they could also be references to XML configuration or to packages that should be scanned.
|
||||
|
||||
It is also possible to configure the `SpringApplication` by using an `application.properties` file.
|
||||
See _<<features#features.external-config>>_ for details.
|
||||
|
||||
For a complete list of the configuration options, see the {spring-boot-module-api}/SpringApplication.html[`SpringApplication` Javadoc].
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.fluent-builder-api]]
|
||||
=== Fluent Builder API
|
||||
If you need to build an `ApplicationContext` hierarchy (multiple contexts with a parent/child relationship) or if you prefer using a "`fluent`" builder API, you can use the `SpringApplicationBuilder`.
|
||||
|
||||
The `SpringApplicationBuilder` lets you chain together multiple method calls and includes `parent` and `child` methods that let you create a hierarchy, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/SpringApplicationBuilderExample.java[tag=*]
|
||||
----
|
||||
|
||||
NOTE: There are some restrictions when creating an `ApplicationContext` hierarchy.
|
||||
For example, Web components *must* be contained within the child context, and the same `Environment` is used for both parent and child contexts.
|
||||
See the {spring-boot-module-api}/builder/SpringApplicationBuilder.html[`SpringApplicationBuilder` Javadoc] for full details.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.application-availability]]
|
||||
=== Application Availability
|
||||
When deployed on platforms, applications can provide information about their availability to the platform using infrastructure such as https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/[Kubernetes Probes].
|
||||
Spring Boot includes out-of-the box support for the commonly used "`liveness`" and "`readiness`" availability states.
|
||||
If you are using Spring Boot's "`actuator`" support then these states are exposed as health endpoint groups.
|
||||
|
||||
In addition, you can also obtain availability states by injecting the `ApplicationAvailability` interface into your own beans.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.application-availability.liveness]]
|
||||
==== Liveness State
|
||||
The "`Liveness`" state of an application tells whether its internal state allows it to work correctly, or recover by itself if it's currently failing.
|
||||
A broken "`Liveness`" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application.
|
||||
|
||||
NOTE: In general, the "Liveness" state should not be based on external checks, such as <<actuator#actuator.endpoints.health, Health checks>>.
|
||||
If it did, a failing external system (a database, a Web API, an external cache) would trigger massive restarts and cascading failures across the platform.
|
||||
|
||||
The internal state of Spring Boot applications is mostly represented by the Spring `ApplicationContext`.
|
||||
If the application context has started successfully, Spring Boot assumes that the application is in a valid state.
|
||||
An application is considered live as soon as the context has been refreshed, see <<features#features.spring-application.application-events-and-listeners, Spring Boot application lifecycle and related Application Events>>.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.application-availability.readiness]]
|
||||
==== Readiness State
|
||||
The "`Readiness`" state of an application tells whether the application is ready to handle traffic.
|
||||
A failing "`Readiness`" state tells the platform that it should not route traffic to the application for now.
|
||||
This typically happens during startup, while `CommandLineRunner` and `ApplicationRunner` components are being processed, or at any time if the application decides that it's too busy for additional traffic.
|
||||
|
||||
An application is considered ready as soon as application and command-line runners have been called, see <<features#features.spring-application.application-events-and-listeners, Spring Boot application lifecycle and related Application Events>>.
|
||||
|
||||
TIP: Tasks expected to run during startup should be executed by `CommandLineRunner` and `ApplicationRunner` components instead of using Spring component lifecycle callbacks such as `@PostConstruct`.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.application-availability.managing]]
|
||||
==== Managing the Application Availability State
|
||||
Application components can retrieve the current availability state at any time, by injecting the `ApplicationAvailability` interface and calling methods on it.
|
||||
More often, applications will want to listen to state updates or update the state of the application.
|
||||
|
||||
For example, we can export the "Readiness" state of the application to a file so that a Kubernetes "exec Probe" can look at this file:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/availability/ReadinessStateExporter.java[]
|
||||
----
|
||||
|
||||
We can also update the state of the application, when the application breaks and cannot recover:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/availability/LocalCacheVerifier.java[]
|
||||
----
|
||||
|
||||
Spring Boot provides <<actuator#actuator.endpoints.kubernetes-probes,Kubernetes HTTP probes for "Liveness" and "Readiness" with Actuator Health Endpoints>>.
|
||||
You can get more guidance about <<deployment#deployment.cloud.kubernetes,deploying Spring Boot applications on Kubernetes in the dedicated section>>.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.application-events-and-listeners]]
|
||||
=== Application Events and Listeners
|
||||
In addition to the usual Spring Framework events, such as {spring-framework-api}/context/event/ContextRefreshedEvent.html[`ContextRefreshedEvent`], a `SpringApplication` sends some additional application events.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Some events are actually triggered before the `ApplicationContext` is created, so you cannot register a listener on those as a `@Bean`.
|
||||
You can register them with the `SpringApplication.addListeners(...)` method or the `SpringApplicationBuilder.listeners(...)` method.
|
||||
|
||||
If you want those listeners to be registered automatically, regardless of the way the application is created, you can add a `META-INF/spring.factories` file to your project and reference your listener(s) by using the `org.springframework.context.ApplicationListener` key, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
org.springframework.context.ApplicationListener=com.example.project.MyListener
|
||||
----
|
||||
|
||||
====
|
||||
|
||||
Application events are sent in the following order, as your application runs:
|
||||
|
||||
. An `ApplicationStartingEvent` is sent at the start of a run but before any processing, except for the registration of listeners and initializers.
|
||||
. An `ApplicationEnvironmentPreparedEvent` is sent when the `Environment` to be used in the context is known but before the context is created.
|
||||
. An `ApplicationContextInitializedEvent` is sent when the `ApplicationContext` is prepared and ApplicationContextInitializers have been called but before any bean definitions are loaded.
|
||||
. An `ApplicationPreparedEvent` is sent just before the refresh is started but after bean definitions have been loaded.
|
||||
. An `ApplicationStartedEvent` is sent after the context has been refreshed but before any application and command-line runners have been called.
|
||||
. An `AvailabilityChangeEvent` is sent right after with `LivenessState.CORRECT` to indicate that the application is considered as live.
|
||||
. An `ApplicationReadyEvent` is sent after any <<features#features.spring-application.command-line-runner,application and command-line runners>> have been called.
|
||||
. An `AvailabilityChangeEvent` is sent right after with `ReadinessState.ACCEPTING_TRAFFIC` to indicate that the application is ready to service requests.
|
||||
. An `ApplicationFailedEvent` is sent if there is an exception on startup.
|
||||
|
||||
The above list only includes ``SpringApplicationEvent``s that are tied to a `SpringApplication`.
|
||||
In addition to these, the following events are also published after `ApplicationPreparedEvent` and before `ApplicationStartedEvent`:
|
||||
|
||||
- A `WebServerInitializedEvent` is sent after the `WebServer` is ready.
|
||||
`ServletWebServerInitializedEvent` and `ReactiveWebServerInitializedEvent` are the servlet and reactive variants respectively.
|
||||
- A `ContextRefreshedEvent` is sent when an `ApplicationContext` is refreshed.
|
||||
|
||||
TIP: You often need not use application events, but it can be handy to know that they exist.
|
||||
Internally, Spring Boot uses events to handle a variety of tasks.
|
||||
|
||||
NOTE: Event listeners should not run potentially lengthy tasks as they execute in the same thread by default.
|
||||
Consider using <<features#features.spring-application.command-line-runner,application and command-line runners>> instead.
|
||||
|
||||
Application events are sent by using Spring Framework's event publishing mechanism.
|
||||
Part of this mechanism ensures that an event published to the listeners in a child context is also published to the listeners in any ancestor contexts.
|
||||
As a result of this, if your application uses a hierarchy of `SpringApplication` instances, a listener may receive multiple instances of the same type of application event.
|
||||
|
||||
To allow your listener to distinguish between an event for its context and an event for a descendant context, it should request that its application context is injected and then compare the injected context with the context of the event.
|
||||
The context can be injected by implementing `ApplicationContextAware` or, if the listener is a bean, by using `@Autowired`.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.web-environment]]
|
||||
=== Web Environment
|
||||
A `SpringApplication` attempts to create the right type of `ApplicationContext` on your behalf.
|
||||
The algorithm used to determine a `WebApplicationType` is the following:
|
||||
|
||||
* If Spring MVC is present, an `AnnotationConfigServletWebServerApplicationContext` is used
|
||||
* If Spring MVC is not present and Spring WebFlux is present, an `AnnotationConfigReactiveWebServerApplicationContext` is used
|
||||
* Otherwise, `AnnotationConfigApplicationContext` is used
|
||||
|
||||
This means that if you are using Spring MVC and the new `WebClient` from Spring WebFlux in the same application, Spring MVC will be used by default.
|
||||
You can override that easily by calling `setWebApplicationType(WebApplicationType)`.
|
||||
|
||||
It is also possible to take complete control of the `ApplicationContext` type that is used by calling `setApplicationContextClass(...)`.
|
||||
|
||||
TIP: It is often desirable to call `setWebApplicationType(WebApplicationType.NONE)` when using `SpringApplication` within a JUnit test.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.application-arguments]]
|
||||
=== Accessing Application Arguments
|
||||
If you need to access the application arguments that were passed to `SpringApplication.run(...)`, you can inject a `org.springframework.boot.ApplicationArguments` bean.
|
||||
The `ApplicationArguments` interface provides access to both the raw `String[]` arguments as well as parsed `option` and `non-option` arguments, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/ApplicationArgumentsExample.java[]
|
||||
----
|
||||
|
||||
TIP: Spring Boot also registers a `CommandLinePropertySource` with the Spring `Environment`.
|
||||
This lets you also inject single application arguments by using the `@Value` annotation.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.command-line-runner]]
|
||||
=== Using the ApplicationRunner or CommandLineRunner
|
||||
If you need to run some specific code once the `SpringApplication` has started, you can implement the `ApplicationRunner` or `CommandLineRunner` interfaces.
|
||||
Both interfaces work in the same way and offer a single `run` method, which is called just before `SpringApplication.run(...)` completes.
|
||||
|
||||
NOTE: This contract is well suited for tasks that should run after application startup but before it starts accepting traffic.
|
||||
|
||||
|
||||
The `CommandLineRunner` interfaces provides access to application arguments as a string array, whereas the `ApplicationRunner` uses the `ApplicationArguments` interface discussed earlier.
|
||||
The following example shows a `CommandLineRunner` with a `run` method:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/CommandLineRunnerExample.java[]
|
||||
----
|
||||
|
||||
If several `CommandLineRunner` or `ApplicationRunner` beans are defined that must be called in a specific order, you can additionally implement the `org.springframework.core.Ordered` interface or use the `org.springframework.core.annotation.Order` annotation.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.application-exit]]
|
||||
=== Application Exit
|
||||
Each `SpringApplication` registers a shutdown hook with the JVM to ensure that the `ApplicationContext` closes gracefully on exit.
|
||||
All the standard Spring lifecycle callbacks (such as the `DisposableBean` interface or the `@PreDestroy` annotation) can be used.
|
||||
|
||||
In addition, beans may implement the `org.springframework.boot.ExitCodeGenerator` interface if they wish to return a specific exit code when `SpringApplication.exit()` is called.
|
||||
This exit code can then be passed to `System.exit()` to return it as a status code, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/exitcode/MyApplication.java[]
|
||||
----
|
||||
|
||||
Also, the `ExitCodeGenerator` interface may be implemented by exceptions.
|
||||
When such an exception is encountered, Spring Boot returns the exit code provided by the implemented `getExitCode()` method.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.admin]]
|
||||
=== Admin Features
|
||||
It is possible to enable admin-related features for the application by specifying the configprop:spring.application.admin.enabled[] property.
|
||||
This exposes the {spring-boot-module-code}/admin/SpringApplicationAdminMXBean.java[`SpringApplicationAdminMXBean`] on the platform `MBeanServer`.
|
||||
You could use this feature to administer your Spring Boot application remotely.
|
||||
This feature could also be useful for any service wrapper implementation.
|
||||
|
||||
TIP: If you want to know on which HTTP port the application is running, get the property with a key of `local.server.port`.
|
||||
|
||||
|
||||
|
||||
[[features.spring-application.startup-tracking]]
|
||||
=== Application Startup tracking
|
||||
During the application startup, the `SpringApplication` and the `ApplicationContext` perform many tasks related to the application lifecycle,
|
||||
the beans lifecycle or even processing application events.
|
||||
With {spring-framework-api}/core/metrics/ApplicationStartup.html[`ApplicationStartup`], Spring Framework {spring-framework-docs}/core.html#context-functionality-startup[allows you to track the application startup sequence with ``StartupStep``s].
|
||||
This data can be collected for profiling purposes, or just to have a better understanding of an application startup process.
|
||||
|
||||
You can choose an `ApplicationStartup` implementation when setting up the `SpringApplication` instance.
|
||||
For example, to use the `BufferingApplicationStartup`, you could write:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
include::{include-springbootfeatures}/springapplication/startup/MyApplication.java[tag=*]
|
||||
----
|
||||
|
||||
The first available implementation, `FlightRecorderApplicationStartup` is provided by Spring Framework.
|
||||
It adds Spring-specific startup events to a Java Flight Recorder session and is meant for profiling applications and correlating their Spring context lifecycle with JVM events (such as allocations, GCs, class loading...).
|
||||
Once configured, you can record data by running the application with the Flight Recorder enabled:
|
||||
|
||||
[source,bash,indent=0]
|
||||
----
|
||||
$ java -XX:StartFlightRecording:filename=recording.jfr,duration=10s -jar demo.jar
|
||||
----
|
||||
|
||||
Spring Boot ships with the `BufferingApplicationStartup` variant; this implementation is meant for buffering the startup steps and draining them into an external metrics system.
|
||||
Applications can ask for the bean of type `BufferingApplicationStartup` in any component.
|
||||
Additionally, Spring Boot Actuator will {spring-boot-actuator-restapi-docs}/#startup[expose a `startup` endpoint to expose this information as a JSON document].
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
[[features.spring-integration]]
|
||||
== Spring Integration
|
||||
Spring Boot offers several conveniences for working with {spring-integration}[Spring Integration], including the `spring-boot-starter-integration` "`Starter`".
|
||||
Spring Integration provides abstractions over messaging and also other transports such as HTTP, TCP, and others.
|
||||
If Spring Integration is available on your classpath, it is initialized through the `@EnableIntegration` annotation.
|
||||
|
||||
Spring Integration polling logic relies <<features#features.task-execution-and-scheduling,on the auto-configured `TaskScheduler`>>.
|
||||
|
||||
Spring Boot also configures some features that are triggered by the presence of additional Spring Integration modules.
|
||||
If `spring-integration-jmx` is also on the classpath, message processing statistics are published over JMX.
|
||||
If `spring-integration-jdbc` is available, the default database schema can be created on startup, as shown in the following line:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
integration:
|
||||
jdbc:
|
||||
initialize-schema: "always"
|
||||
----
|
||||
|
||||
If `spring-integration-rsocket` is available, developers can configure an RSocket server using `"spring.rsocket.server.*"` properties and let it use `IntegrationRSocketEndpoint` or `RSocketOutboundGateway` components to handle incoming RSocket messages.
|
||||
This infrastructure can handle Spring Integration RSocket channel adapters and `@MessageMapping` handlers (given `"spring.integration.rsocket.server.message-mapping-enabled"` is configured).
|
||||
|
||||
Spring Boot can also auto-configure an `ClientRSocketConnector` using configuration properties:
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
# Connecting to a RSocket server over TCP
|
||||
spring:
|
||||
integration:
|
||||
rsocket:
|
||||
client:
|
||||
host: "example.org"
|
||||
port: 9898
|
||||
----
|
||||
|
||||
[source,yaml,indent=0,configprops,configblocks]
|
||||
----
|
||||
# Connecting to a RSocket Server over WebSocket
|
||||
spring:
|
||||
integration:
|
||||
rsocket:
|
||||
client:
|
||||
uri: "ws://example.org"
|
||||
----
|
||||
|
||||
See the {spring-boot-autoconfigure-module-code}/integration/IntegrationAutoConfiguration.java[`IntegrationAutoConfiguration`] and {spring-boot-autoconfigure-module-code}/integration/IntegrationProperties.java[`IntegrationProperties`] classes for more details.
|
||||
|
||||
By default, if a Micrometer `meterRegistry` bean is present, Spring Integration metrics will be managed by Micrometer.
|
||||
If you wish to use legacy Spring Integration metrics, add a `DefaultMetricsFactory` bean to the application context.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue