Spring Boot Reference Guide
2.1.0.BUILD-SNAPSHOT
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
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.
Spring Boot Reference Guide
2.1.0.BUILD-SNAPSHOT Spring Boot ii
Table of Contents
I. Spring Boot Documentation ...................................................................................................... 1
1. About the Documentation ................................................................................................ 2
2. Getting Help ................................................................................................................... 3
3. First Steps ...................................................................................................................... 4
4. Working with Spring Boot ................................................................................................ 5
5. Learning about Spring Boot Features .............................................................................. 6
6. Moving to Production ...................................................................................................... 7
7. Advanced Topics ............................................................................................................ 8
II. Getting Started ....................................................................................................................... 9
8. Introducing Spring Boot ................................................................................................. 10
9. System Requirements ................................................................................................... 11
9.1. Servlet Containers .............................................................................................. 11
10. Installing Spring Boot .................................................................................................. 12
10.1. Installation Instructions for the Java Developer .................................................. 12
Maven Installation ............................................................................................. 12
Gradle Installation ............................................................................................. 13
10.2. Installing the Spring Boot CLI ........................................................................... 14
Manual Installation ............................................................................................ 14
Installation with SDKMAN! ................................................................................. 14
OSX Homebrew Installation ............................................................................... 15
MacPorts Installation ......................................................................................... 15
Command-line Completion ................................................................................ 15
Windows Scoop Installation ............................................................................... 16
Quick-start Spring CLI Example ......................................................................... 16
10.3. Upgrading from an Earlier Version of Spring Boot .............................................. 17
11. Developing Your First Spring Boot Application .............................................................. 18
11.1. Creating the POM ............................................................................................ 18
11.2. Adding Classpath Dependencies ....................................................................... 19
11.3. Writing the Code .............................................................................................. 20
The @RestController and @RequestMapping Annotations .................................. 20
The @EnableAutoConfiguration Annotation ........................................................ 20
The “main” Method ........................................................................................... 21
11.4. Running the Example ....................................................................................... 21
11.5. Creating an Executable Jar ............................................................................... 21
12. What to Read Next ..................................................................................................... 23
III. Using Spring Boot ................................................................................................................ 24
13. Build Systems ............................................................................................................. 25
13.1. Dependency Management ................................................................................ 25
13.2. Maven ............................................................................................................. 25
Inheriting the Starter Parent .............................................................................. 26
Using Spring Boot without the Parent POM ........................................................ 26
Using the Spring Boot Maven Plugin ................................................................. 27
13.3. Gradle ............................................................................................................. 27
13.4. Ant .................................................................................................................. 27
13.5. Starters ............................................................................................................ 28
14. Structuring Your Code ................................................................................................. 34
14.1. Using the “default” Package .............................................................................. 34
Spring Boot Reference Guide
2.1.0.BUILD-SNAPSHOT Spring Boot iii
14.2. Locating the Main Application Class .................................................................. 34
15. Configuration Classes ................................................................................................. 36
15.1. Importing Additional Configuration Classes ........................................................ 36
15.2. Importing XML Configuration ............................................................................. 36
16. Auto-configuration ....................................................................................................... 37
16.1. Gradually Replacing Auto-configuration ............................................................. 37
16.2. Disabling Specific Auto-configuration Classes .................................................... 37
17. Spring Beans and Dependency Injection ...................................................................... 38
18. Using the @SpringBootApplication Annotation .............................................................. 39
19. Running Your Application ............................................................................................ 41
19.1. Running from an IDE ....................................................................................... 41
19.2. Running as a Packaged Application .................................................................. 41
19.3. Using the Maven Plugin ................................................................................... 41
19.4. Using the Gradle Plugin ................................................................................... 42
19.5. Hot Swapping .................................................................................................. 42
20. Developer Tools .......................................................................................................... 43
20.1. Property Defaults ............................................................................................. 43
20.2. Automatic Restart ............................................................................................. 44
Logging changes in condition evaluation ............................................................ 45
Excluding Resources ......................................................................................... 45
Watching Additional Paths ................................................................................. 45
Disabling Restart .............................................................................................. 46
Using a Trigger File .......................................................................................... 46
Customizing the Restart Classloader ................................................................. 46
Known Limitations ............................................................................................. 47
20.3. LiveReload ....................................................................................................... 47
20.4. Global Settings ................................................................................................. 47
20.5. Remote Applications ......................................................................................... 47
Running the Remote Client Application .............................................................. 48
Remote Update ................................................................................................ 49
21. Packaging Your Application for Production ................................................................... 50
22. What to Read Next ..................................................................................................... 51
IV. Spring Boot features ............................................................................................................ 52
23. SpringApplication ........................................................................................................ 53
23.1. Startup Failure ................................................................................................. 53
23.2. Customizing the Banner ................................................................................... 54
23.3. Customizing SpringApplication .......................................................................... 55
23.4. Fluent Builder API ............................................................................................ 55
23.5. Application Events and Listeners ...................................................................... 56
23.6. Web Environment ............................................................................................. 57
23.7. Accessing Application Arguments ...................................................................... 57
23.8. Using the ApplicationRunner or CommandLineRunner ....................................... 58
23.9. Application Exit ................................................................................................ 58
23.10. Admin Features .............................................................................................. 59
24. Externalized Configuration ........................................................................................... 60
24.1. Configuring Random Values ............................................................................. 61
24.2. Accessing Command Line Properties ................................................................ 61
24.3. Application Property Files ................................................................................. 62
24.4. Profile-specific Properties ................................................................................. 63
24.5. Placeholders in Properties ................................................................................ 64
Spring Boot Reference Guide
2.1.0.BUILD-SNAPSHOT Spring Boot iv
24.6. Using YAML Instead of Properties .................................................................... 64
Loading YAML .................................................................................................. 64
Exposing YAML as Properties in the Spring Environment .................................... 65
Multi-profile YAML Documents ........................................................................... 65
YAML Shortcomings ......................................................................................... 66
24.7. Type-safe Configuration Properties ................................................................... 66
Third-party Configuration ................................................................................... 69
Relaxed Binding ................................................................................................ 69
Merging Complex Types ................................................................................... 71
Properties Conversion ....................................................................................... 72
Converting durations ................................................................................. 73
Converting Data Sizes .............................................................................. 74
@ConfigurationProperties Validation .................................................................. 75
@ConfigurationProperties vs. @Value ............................................................... 76
25. Profiles ....................................................................................................................... 77
25.1. Adding Active Profiles ...................................................................................... 77
25.2. Programmatically Setting Profiles ...................................................................... 78
25.3. Profile-specific Configuration Files ..................................................................... 78
26. Logging ...................................................................................................................... 79
26.1. Log Format ...................................................................................................... 79
26.2. Console Output ................................................................................................ 79
Color-coded Output ........................................................................................... 80
26.3. File Output ....................................................................................................... 81
26.4. Log Levels ....................................................................................................... 81
26.5. Log Groups ...................................................................................................... 82
26.6. Custom Log Configuration ................................................................................ 82
26.7. Logback Extensions ......................................................................................... 84
Profile-specific Configuration ............................................................................. 85
Environment Properties ..................................................................................... 85
27. Developing Web Applications ...................................................................................... 86
27.1. The “Spring Web MVC Framework” .................................................................. 86
Spring MVC Auto-configuration .......................................................................... 86
HttpMessageConverters .................................................................................... 87
Custom JSON Serializers and Deserializers ....................................................... 87
MessageCodesResolver .................................................................................... 88
Static Content ................................................................................................... 88
Welcome Page ................................................................................................. 90
Custom Favicon ................................................................................................ 90
Path Matching and Content Negotiation ............................................................. 90
ConfigurableWebBindingInitializer ...................................................................... 90
Template Engines ............................................................................................. 91
Error Handling .................................................................................................. 91
Custom Error Pages ................................................................................. 92
Mapping Error Pages outside of Spring MVC ............................................. 93
Spring HATEOAS ............................................................................................. 93
CORS Support .................................................................................................. 94
27.2. The “Spring WebFlux Framework” ..................................................................... 94
Spring WebFlux Auto-configuration .................................................................... 95
HTTP Codecs with HttpMessageReaders and HttpMessageWriters ..................... 96
Static Content ................................................................................................... 96
Spring Boot Reference Guide
2.1.0.BUILD-SNAPSHOT Spring Boot v
Template Engines ............................................................................................. 97
Error Handling .................................................................................................. 97
Custom Error Pages ................................................................................. 98
Web Filters ....................................................................................................... 98
27.3. JAX-RS and Jersey .......................................................................................... 98
27.4. Embedded Servlet Container Support ................................................................ 99
Servlets, Filters, and listeners .......................................................................... 100
Registering Servlets, Filters, and Listeners as Spring Beans ...................... 100
Servlet Context Initialization ............................................................................. 100
Scanning for Servlets, Filters, and listeners .............................................. 101
The ServletWebServerApplicationContext ......................................................... 101
Customizing Embedded Servlet Containers ...................................................... 101
Programmatic Customization ................................................................... 102
Customizing ConfigurableServletWebServerFactory Directly ...................... 102
JSP Limitations ............................................................................................... 103
28. Security .................................................................................................................... 104
28.1. MVC Security ................................................................................................. 104
28.2. WebFlux Security ........................................................................................... 105
28.3. OAuth2 .......................................................................................................... 105
Client .............................................................................................................. 105
OpenID Connect Login client registration .................................................. 106
OAuth2 Authorization Code client registration ........................................... 107
OAuth2 client registration for common providers ....................................... 107
Resource Server ............................................................................................. 107
Authorization Server ........................................................................................ 108
28.4. Actuator Security ............................................................................................ 108
Cross Site Request Forgery Protection ............................................................ 108
29. Working with SQL Databases .................................................................................... 109
29.1. Configure a DataSource ................................................................................. 109
Embedded Database Support .......................................................................... 109
Connection to a Production Database .............................................................. 110
Connection to a JNDI DataSource ................................................................... 111
29.2. Using JdbcTemplate ....................................................................................... 111
29.3. JPA and Spring Data JPA .............................................................................. 112
Entity Classes ................................................................................................. 112
Spring Data JPA Repositories ......................................................................... 113
Creating and Dropping JPA Databases ............................................................ 114
Open EntityManager in View ........................................................................... 114
29.4. Spring Data JDBC .......................................................................................... 114
29.5. Using H2’s Web Console ................................................................................ 115
Changing the H2 Console’s Path ..................................................................... 115
29.6. Using jOOQ ................................................................................................... 115
Code Generation ............................................................................................. 115
Using DSLContext ........................................................................................... 116
jOOQ SQL Dialect .......................................................................................... 116
Customizing jOOQ .......................................................................................... 116
30. Working with NoSQL Technologies ............................................................................ 118
30.1. Redis ............................................................................................................. 118
Connecting to Redis ........................................................................................ 118
30.2. MongoDB ....................................................................................................... 119
