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