Spring Boot Reference Guide

Authors

Phillip Webb, Dave Syer, Josh Long, Stéphane Nicoll, Rob Winch, Andy Wilkinson, Marcel Overdijk, Christian Dupuis, Sébastien Deleuze, Michael Simons, Vedran Pavić, Jay Bryant, Madhura Bhave

2.1.1.RELEASE

Copyright © 2012-2018

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.

Table of Contents

I. Spring Boot Documentation

1. About the Documentation
2. Getting Help
3. First Steps
4. Working with Spring Boot
5. Learning about Spring Boot Features
6. Moving to Production
7. Advanced Topics

II. Getting Started

8. Introducing Spring Boot

9. System Requirements

9.1. Servlet Containers

10. Installing Spring Boot

10.1. Installation Instructions for the Java Developer

10.1.1. Maven Installation
10.1.2. Gradle Installation

10.2. Installing the Spring Boot CLI

10.2.1. Manual Installation
10.2.2. Installation with SDKMAN!
10.2.3. OSX Homebrew Installation
10.2.4. MacPorts Installation
10.2.5. Command-line Completion
10.2.6. Windows Scoop Installation
10.2.7. Quick-start Spring CLI Example

10.3. Upgrading from an Earlier Version of Spring Boot

11. Developing Your First Spring Boot Application

11.1. Creating the POM

11.2. Adding Classpath Dependencies

11.3. Writing the Code

11.3.1. The @RestController and @RequestMapping Annotations
11.3.2. The @EnableAutoConfiguration Annotation
11.3.3. The “main” Method

11.4. Running the Example

11.5. Creating an Executable Jar

12. What to Read Next

III. Using Spring Boot

13. Build Systems

13.1. Dependency Management

13.2. Maven

13.2.1. Inheriting the Starter Parent
13.2.2. Using Spring Boot without the Parent POM
13.2.3. Using the Spring Boot Maven Plugin

13.3. Gradle

13.5. Starters

14. Structuring Your Code

14.1. Using the “default” Package
14.2. Locating the Main Application Class

15. Configuration Classes

15.1. Importing Additional Configuration Classes
15.2. Importing XML Configuration

16. Auto-configuration

16.1. Gradually Replacing Auto-configuration
16.2. Disabling Specific Auto-configuration Classes

17. Spring Beans and Dependency Injection

18. Using the @SpringBootApplication Annotation

19. Running Your Application

19.1. Running from an IDE
19.2. Running as a Packaged Application
19.3. Using the Maven Plugin
19.4. Using the Gradle Plugin
19.5. Hot Swapping

20. Developer Tools

20.1. Property Defaults

20.2. Automatic Restart

20.2.1. Logging changes in condition evaluation
20.2.2. Excluding Resources
20.2.3. Watching Additional Paths
20.2.4. Disabling Restart
20.2.5. Using a Trigger File
20.2.6. Customizing the Restart Classloader
20.2.7. Known Limitations

20.3. LiveReload

20.4. Global Settings

20.5. Remote Applications

20.5.1. Running the Remote Client Application
20.5.2. Remote Update

21. Packaging Your Application for Production

22. What to Read Next

IV. Spring Boot features

23. SpringApplication

23.1. Startup Failure
23.2. Customizing the Banner
23.3. Customizing SpringApplication
23.4. Fluent Builder API
23.5. Application Events and Listeners
23.6. Web Environment
23.7. Accessing Application Arguments
23.8. Using the ApplicationRunner or CommandLineRunner
23.9. Application Exit
23.10. Admin Features

24. Externalized Configuration

24.1. Configuring Random Values

24.2. Accessing Command Line Properties

24.3. Application Property Files

24.4. Profile-specific Properties

24.5. Placeholders in Properties

24.6. Encrypting Properties

24.7. Using YAML Instead of Properties

24.7.1. Loading YAML
24.7.2. Exposing YAML as Properties in the Spring Environment
24.7.3. Multi-profile YAML Documents
24.7.4. YAML Shortcomings

24.8. Type-safe Configuration Properties

24.8.1. Third-party Configuration

24.8.2. Relaxed Binding

24.8.3. Merging Complex Types

24.8.4. Properties Conversion

Converting durations
Converting Data Sizes

24.8.5. @ConfigurationProperties Validation

24.8.6. @ConfigurationProperties vs. @Value

25. Profiles

25.1. Adding Active Profiles
25.2. Programmatically Setting Profiles
25.3. Profile-specific Configuration Files

26. Logging

26.1. Log Format

26.2. Console Output

26.2.1. Color-coded Output

26.3. File Output

26.4. Log Levels

26.5. Log Groups

26.6. Custom Log Configuration

26.7. Logback Extensions

26.7.1. Profile-specific Configuration
26.7.2. Environment Properties

27.1. Jackson
27.2. Gson
27.3. JSON-B

28. Developing Web Applications

28.1. The “Spring Web MVC Framework”

28.1.1. Spring MVC Auto-configuration

28.1.2. HttpMessageConverters

28.1.3. Custom JSON Serializers and Deserializers

28.1.4. MessageCodesResolver

28.1.5. Static Content

28.1.6. Welcome Page

28.1.7. Custom Favicon

28.1.8. Path Matching and Content Negotiation

28.1.9. ConfigurableWebBindingInitializer

28.1.10. Template Engines

28.1.11. Error Handling

Custom Error Pages
Mapping Error Pages outside of Spring MVC

28.1.12. Spring HATEOAS

28.1.13. CORS Support

28.2. The “Spring WebFlux Framework”

28.2.1. Spring WebFlux Auto-configuration

28.2.2. HTTP Codecs with HttpMessageReaders and HttpMessageWriters

28.2.3. Static Content

28.2.4. Template Engines

28.2.5. Error Handling

Custom Error Pages

28.2.6. Web Filters

28.3. JAX-RS and Jersey

28.4. Embedded Servlet Container Support

28.4.1. Servlets, Filters, and listeners

Registering Servlets, Filters, and Listeners as Spring Beans

28.4.2. Servlet Context Initialization

Scanning for Servlets, Filters, and listeners

28.4.3. The ServletWebServerApplicationContext

28.4.4. Customizing Embedded Servlet Containers

Programmatic Customization
Customizing ConfigurableServletWebServerFactory Directly

28.4.5. JSP Limitations

28.5. Embedded Reactive Server Support

28.6. Reactive Server Resources Configuration

29. Security

29.1. MVC Security

29.2. WebFlux Security

29.3. OAuth2

29.3.1. Client

OAuth2 client registration for common providers

29.3.2. Resource Server

29.3.3. Authorization Server

29.4. Actuator Security

29.4.1. Cross Site Request Forgery Protection

30. Working with SQL Databases

30.1. Configure a DataSource

30.1.1. Embedded Database Support
30.1.2. Connection to a Production Database
30.1.3. Connection to a JNDI DataSource

30.2. Using JdbcTemplate

30.3. JPA and Spring Data JPA

30.3.1. Entity Classes
30.3.2. Spring Data JPA Repositories
30.3.3. Creating and Dropping JPA Databases
30.3.4. Open EntityManager in View

30.4. Spring Data JDBC

30.5. Using H2’s Web Console

30.5.1. Changing the H2 Console’s Path

30.6. Using jOOQ

30.6.1. Code Generation
30.6.2. Using DSLContext
30.6.3. jOOQ SQL Dialect
30.6.4. Customizing jOOQ

31. Working with NoSQL Technologies

31.1. Redis

31.1.1. Connecting to Redis

31.2. MongoDB

31.2.1. Connecting to a MongoDB Database
31.2.2. MongoTemplate
31.2.3. Spring Data MongoDB Repositories
31.2.4. Embedded Mongo

31.3. Neo4j

31.3.1. Connecting to a Neo4j Database
31.3.2. Using the Embedded Mode
31.3.3. Neo4jSession
31.3.4. Spring Data Neo4j Repositories

31.4. Gemfire

31.5.1. Connecting to Solr
31.5.2. Spring Data Solr Repositories

31.6. Elasticsearch

31.6.1. Connecting to Elasticsearch by REST clients
31.6.2. Connecting to Elasticsearch by Using Jest
31.6.3. Connecting to Elasticsearch by Using Spring Data
31.6.4. Spring Data Elasticsearch Repositories

31.7. Cassandra

31.7.1. Connecting to Cassandra
31.7.2. Spring Data Cassandra Repositories

31.8. Couchbase

31.8.1. Connecting to Couchbase
31.8.2. Spring Data Couchbase Repositories

31.9.1. Connecting to an LDAP Server
31.9.2. Spring Data LDAP Repositories
31.9.3. Embedded In-memory LDAP Server

31.10. InfluxDB

31.10.1. Connecting to InfluxDB

32. Caching

32.1. Supported Cache Providers

32.1.1. Generic
32.1.2. JCache (JSR-107)
32.1.3. EhCache 2.x
32.1.4. Hazelcast
32.1.5. Infinispan
32.1.6. Couchbase
32.1.7. Redis
32.1.8. Caffeine
32.1.9. Simple
32.1.10. None

33. Messaging

33.1.1. ActiveMQ Support
33.1.2. Artemis Support
33.1.3. Using a JNDI ConnectionFactory
33.1.4. Sending a Message
33.1.5. Receiving a Message

33.2.1. RabbitMQ support
33.2.2. Sending a Message
33.2.3. Receiving a Message

33.3. Apache Kafka Support

33.3.1. Sending a Message
33.3.2. Receiving a Message
33.3.3. Kafka Streams
33.3.4. Additional Kafka Properties

34. Calling REST Services with RestTemplate

34.1. RestTemplate Customization

35. Calling REST Services with WebClient

35.1. WebClient Runtime
35.2. WebClient Customization

36. Validation

37. Sending Email

38. Distributed Transactions with JTA

38.1. Using an Atomikos Transaction Manager
38.2. Using a Bitronix Transaction Manager
38.3. Using a Java EE Managed Transaction Manager
38.4. Mixing XA and Non-XA JMS Connections
38.5. Supporting an Alternative Embedded Transaction Manager

39. Hazelcast

40. Quartz Scheduler

41. Task Execution and Scheduling

42. Spring Integration

43. Spring Session

44. Monitoring and Management over JMX

45. Testing

45.1. Test Scope Dependencies

45.2. Testing Spring Applications

45.3. Testing Spring Boot Applications

45.3.1. Detecting Web Application Type

45.3.2. Detecting Test Configuration

45.3.3. Excluding Test Configuration

45.3.4. Testing with a mock environment

45.3.5. Testing with a running server

45.3.6. Using JMX

45.3.7. Mocking and Spying Beans

45.3.8. Auto-configured Tests

45.3.9. Auto-configured JSON Tests

45.3.10. Auto-configured Spring MVC Tests

45.3.11. Auto-configured Spring WebFlux Tests

45.3.12. Auto-configured Data JPA Tests

45.3.13. Auto-configured JDBC Tests

45.3.14. Auto-configured Data JDBC Tests

45.3.15. Auto-configured jOOQ Tests

45.3.16. Auto-configured Data MongoDB Tests

45.3.17. Auto-configured Data Neo4j Tests

45.3.18. Auto-configured Data Redis Tests

45.3.19. Auto-configured Data LDAP Tests

45.3.20. Auto-configured REST Clients

45.3.21. Auto-configured Spring REST Docs Tests

Auto-configured Spring REST Docs Tests with Mock MVC
Auto-configured Spring REST Docs Tests with REST Assured

45.3.22. Additional Auto-configuration and Slicing

45.3.23. User Configuration and Slicing

45.3.24. Using Spock to Test Spring Boot Applications

45.4. Test Utilities

45.4.1. ConfigFileApplicationContextInitializer
45.4.2. TestPropertyValues
45.4.3. OutputCapture
45.4.4. TestRestTemplate

46. WebSockets

47. Web Services

48. Calling Web Services with WebServiceTemplate

49. Creating Your Own Auto-configuration

49.1. Understanding Auto-configured Beans

49.2. Locating Auto-configuration Candidates

49.3. Condition Annotations

49.3.1. Class Conditions
49.3.2. Bean Conditions
49.3.3. Property Conditions
49.3.4. Resource Conditions
49.3.5. Web Application Conditions
49.3.6. SpEL Expression Conditions

49.4. Testing your Auto-configuration

49.4.1. Simulating a Web Context
49.4.2. Overriding the Classpath

49.5. Creating Your Own Starter

49.5.1. Naming
49.5.2. autoconfigure Module
49.5.3. Starter Module

50. Kotlin support

50.1. Requirements

50.2. Null-safety

50.3. Kotlin API

50.3.1. runApplication
50.3.2. Extensions

50.4. Dependency management

50.5. @ConfigurationProperties

50.6. Testing

50.7. Resources

50.7.1. Further reading
50.7.2. Examples

51. What to Read Next

V. Spring Boot Actuator: Production-ready features

52. Enabling Production-ready Features

53. Endpoints

53.1. Enabling Endpoints

53.2. Exposing Endpoints

53.3. Securing HTTP Endpoints

53.4. Configuring Endpoints

53.5. Hypermedia for Actuator Web Endpoints

53.6. CORS Support

53.7. Implementing Custom Endpoints

53.7.1. Receiving Input

Input type conversion

53.7.2. Custom Web Endpoints

Web Endpoint Request Predicates
Path
HTTP method
Consumes
Produces
Web Endpoint Response Status
Web Endpoint Range Requests
Web Endpoint Security

53.7.3. Servlet endpoints

53.7.4. Controller endpoints

53.8. Health Information

53.8.1. Auto-configured HealthIndicators
53.8.2. Writing Custom HealthIndicators
53.8.3. Reactive Health Indicators
53.8.4. Auto-configured ReactiveHealthIndicators

53.9. Application Information

53.9.1. Auto-configured InfoContributors
53.9.2. Custom Application Information
53.9.3. Git Commit Information
53.9.4. Build Information
53.9.5. Writing Custom InfoContributors

54. Monitoring and Management over HTTP

54.1. Customizing the Management Endpoint Paths
54.2. Customizing the Management Server Port
54.3. Configuring Management-specific SSL
54.4. Customizing the Management Server Address
54.5. Disabling HTTP Endpoints

55. Monitoring and Management over JMX

55.1. Customizing MBean Names

55.2. Disabling JMX Endpoints

55.3. Using Jolokia for JMX over HTTP

55.3.1. Customizing Jolokia
55.3.2. Disabling Jolokia

56. Loggers

56.1. Configure a Logger

57. Metrics

57.1. Getting started

57.2. Supported monitoring systems

57.2.1. AppOptics
57.2.2. Atlas
57.2.3. Datadog
57.2.4. Dynatrace
57.2.5. Elastic
57.2.6. Ganglia
57.2.7. Graphite
57.2.8. Humio
57.2.9. Influx
57.2.10. JMX
57.2.11. KairosDB
57.2.12. New Relic
57.2.13. Prometheus
57.2.14. SignalFx
57.2.15. Simple
57.2.16. StatsD
57.2.17. Wavefront

57.3. Supported Metrics

57.3.1. Spring MVC Metrics
57.3.2. Spring WebFlux Metrics
57.3.3. Jersey Server Metrics
57.3.4. HTTP Client Metrics
57.3.5. Cache Metrics
57.3.6. DataSource Metrics
57.3.7. Hibernate Metrics
57.3.8. RabbitMQ Metrics

57.4. Registering custom metrics

57.5. Customizing individual metrics

57.5.1. Common tags
57.5.2. Per-meter properties

57.6. Metrics endpoint

58. Auditing

59. HTTP Tracing

59.1. Custom HTTP tracing

60. Process Monitoring

60.1. Extending Configuration
60.2. Programmatically

61. Cloud Foundry Support

61.1. Disabling Extended Cloud Foundry Actuator Support
61.2. Cloud Foundry Self-signed Certificates
61.3. Custom context path

62. What to Read Next

VI. Deploying Spring Boot Applications

63. Deploying to the Cloud

63.1. Cloud Foundry

63.1.1. Binding to Services

63.2. Heroku

63.3. OpenShift

63.4. Amazon Web Services (AWS)

63.4.1. AWS Elastic Beanstalk

Using the Tomcat Platform
Using the Java SE Platform

63.4.2. Summary

63.5. Boxfuse and Amazon Web Services

63.6. Google Cloud

64. Installing Spring Boot Applications

64.1. Supported Operating Systems

64.2. Unix/Linux Services

64.2.1. Installation as an init.d Service (System V)

Securing an init.d Service

64.2.2. Installation as a systemd Service

64.2.3. Customizing the Startup Script

Customizing the Start Script when It Is Written
Customizing a Script When It Runs

64.3. Microsoft Windows Services

65. What to Read Next

VII. Spring Boot CLI

66. Installing the CLI

67. Using the CLI

67.1. Running Applications with the CLI

67.1.1. Deduced “grab” Dependencies
67.1.2. Deduced “grab” Coordinates
67.1.3. Default Import Statements
67.1.4. Automatic Main Method
67.1.5. Custom Dependency Management

67.2. Applications with Multiple Source Files

67.3. Packaging Your Application

67.4. Initialize a New Project

67.5. Using the Embedded Shell

67.6. Adding Extensions to the CLI

68. Developing Applications with the Groovy Beans DSL

69. Configuring the CLI with settings.xml

70. What to Read Next

VIII. Build tool plugins

71. Spring Boot Maven Plugin

71.1. Including the Plugin
71.2. Packaging Executable Jar and War Files

72. Spring Boot Gradle Plugin

73. Spring Boot AntLib Module

73.1. Spring Boot Ant Tasks

73.1.1. spring-boot:exejar
73.1.2. Examples

73.2. spring-boot:findmainclass

73.2.1. Examples

74. Supporting Other Build Systems

74.1. Repackaging Archives
74.2. Nested Libraries
74.3. Finding a Main Class
74.4. Example Repackage Implementation

75. What to Read Next

IX. ‘How-to’ guides

76. Spring Boot Application

76.1. Create Your Own FailureAnalyzer
76.2. Troubleshoot Auto-configuration
76.3. Customize the Environment or ApplicationContext Before It Starts
76.4. Build an ApplicationContext Hierarchy (Adding a Parent or Root Context)
76.5. Create a Non-web Application

77. Properties and Configuration

77.1. Automatically Expand Properties at Build Time

77.1.1. Automatic Property Expansion Using Maven
77.1.2. Automatic Property Expansion Using Gradle

77.2. Externalize the Configuration of SpringApplication

77.3. Change the Location of External Properties of an Application

77.4. Use ‘Short’ Command Line Arguments

77.5. Use YAML for External Properties

77.6. Set the Active Spring Profiles

77.7. Change Configuration Depending on the Environment

77.8. Discover Built-in Options for External Properties

78. Embedded Web Servers

78.1. Use Another Web Server

78.2. Disabling the Web Server

78.3. Change the HTTP Port

78.4. Use a Random Unassigned HTTP Port

78.5. Discover the HTTP Port at Runtime

78.6. Enable HTTP Response Compression

78.7. Configure SSL

78.8. Configure HTTP/2

78.8.1. HTTP/2 with Undertow
78.8.2. HTTP/2 with Jetty
78.8.3. HTTP/2 with Tomcat
78.8.4. HTTP/2 with Reactor Netty

78.9. Configure the Web Server

78.10. Add a Servlet, Filter, or Listener to an Application

78.10.1. Add a Servlet, Filter, or Listener by Using a Spring Bean

Disable Registration of a Servlet or Filter

78.10.2. Add Servlets, Filters, and Listeners by Using Classpath Scanning

78.11. Configure Access Logging

78.12. Running Behind a Front-end Proxy Server

78.12.1. Customize Tomcat’s Proxy Configuration

78.13. Enable Multiple Connectors with Tomcat

78.14. Use Tomcat’s LegacyCookieProcessor

78.15. Enable Multiple Listeners with Undertow

78.16. Create WebSocket Endpoints Using @ServerEndpoint

79. Spring MVC

79.1. Write a JSON REST Service
79.2. Write an XML REST Service
79.3. Customize the Jackson ObjectMapper
79.4. Customize the @ResponseBody Rendering
79.5. Handling Multipart File Uploads
79.6. Switch Off the Spring MVC DispatcherServlet
79.7. Switch off the Default MVC Configuration
79.8. Customize ViewResolvers

80. Testing With Spring Security

81.1. Secure Jersey endpoints with Spring Security

82. HTTP Clients

82.1. Configure RestTemplate to Use a Proxy

83. Logging

83.1. Configure Logback for Logging

83.1.1. Configure Logback for File-only Output

83.2. Configure Log4j for Logging

83.2.1. Use YAML or JSON to Configure Log4j 2

84. Data Access

84.1. Configure a Custom DataSource
84.2. Configure Two DataSources
84.3. Use Spring Data Repositories
84.4. Separate @Entity Definitions from Spring Configuration
84.5. Configure JPA Properties
84.6. Configure Hibernate Naming Strategy
84.7. Configure Hibernate Second-Level Caching
84.8. Use Dependency Injection in Hibernate Components
84.9. Use a Custom EntityManagerFactory
84.10. Use Two EntityManagers
84.11. Use a Traditional persistence.xml File
84.12. Use Spring Data JPA and Mongo Repositories
84.13. Customize Spring Data’s Web Support
84.14. Expose Spring Data Repositories as REST Endpoint
84.15. Configure a Component that is Used by JPA
84.16. Configure jOOQ with Two DataSources

85. Database Initialization

85.1. Initialize a Database Using JPA

85.2. Initialize a Database Using Hibernate

85.3. Initialize a Database

85.4. Initialize a Spring Batch Database

85.5. Use a Higher-level Database Migration Tool

85.5.1. Execute Flyway Database Migrations on Startup
85.5.2. Execute Liquibase Database Migrations on Startup

86. Messaging

86.1. Disable Transacted JMS Session

87. Batch Applications

87.1. Execute Spring Batch Jobs on Startup

88. Actuator

88.1. Change the HTTP Port or Address of the Actuator Endpoints
88.2. Customize the ‘whitelabel’ Error Page
88.3. Sanitize sensible values

89. Security

89.1. Switch off the Spring Boot Security Configuration
89.2. Change the UserDetailsService and Add User Accounts
89.3. Enable HTTPS When Running behind a Proxy Server

90. Hot Swapping

90.1. Reload Static Content

90.2. Reload Templates without Restarting the Container

90.2.1. Thymeleaf Templates
90.2.2. FreeMarker Templates
90.2.3. Groovy Templates

90.3. Fast Application Restarts

90.4. Reload Java Classes without Restarting the Container

91.1. Generate Build Information
91.2. Generate Git Information
91.3. Customize Dependency Versions
91.4. Create an Executable JAR with Maven
91.5. Use a Spring Boot Application as a Dependency
91.6. Extract Specific Libraries When an Executable Jar Runs
91.7. Create a Non-executable JAR with Exclusions
91.8. Remote Debug a Spring Boot Application Started with Maven
91.9. Build an Executable Archive from Ant without Using spring-boot-antlib

92. Traditional Deployment

92.1. Create a Deployable War File
92.2. Convert an Existing Application to Spring Boot
92.3. Deploying a WAR to WebLogic
92.4. Use Jedis Instead of Lettuce

X. Appendices

A. Common application properties

B. Configuration Metadata

B.1. Metadata Format

B.1.1. Group Attributes
B.1.2. Property Attributes
B.1.3. Hint Attributes
B.1.4. Repeated Metadata Items

B.2. Providing Manual Hints

B.2.1. Value Hint

B.2.2. Value Providers

Any
Class Reference
Handle As
Logger Name
Spring Bean Reference
Spring Profile Name

B.3. Generating Your Own Metadata by Using the Annotation Processor

B.3.1. Nested Properties
B.3.2. Adding Additional Metadata

C. Auto-configuration classes

C.1. From the “spring-boot-autoconfigure” module
C.2. From the “spring-boot-actuator-autoconfigure” module

D. Test auto-configuration annotations

E. The Executable Jar Format

E.1. Nested JARs

E.1.1. The Executable Jar File Structure
E.1.2. The Executable War File Structure

E.2. Spring Boot’s “JarFile” Class

E.2.1. Compatibility with the Standard Java “JarFile”

E.3. Launching Executable Jars

E.3.1. Launcher Manifest
E.3.2. Exploded Archives

E.4. PropertiesLauncher Features

E.5. Executable Jar Restrictions

E.6. Alternative Single Jar Solutions

F. Dependency versions