Spring Boot Reference Guide
2.0.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
Copyright © 2012-2017
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.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
Quick-start Spring CLI Example ......................................................................... 16
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 .............................................................................................. 19
The @RestController and @RequestMapping Annotations .................................. 19
The @EnableAutoConfiguration Annotation ........................................................ 19
The “main” Method ........................................................................................... 20
11.4. Running the Example ....................................................................................... 20
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.BUILD-SNAPSHOT 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
Excluding Resources ......................................................................................... 43
Watching Additional Paths ................................................................................. 43
Disabling Restart .............................................................................................. 43
Using a Trigger File .......................................................................................... 44
Customizing the Restart Classloader ................................................................. 44
Known Limitations ............................................................................................. 44
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. Customizing the Banner ................................................................................... 52
23.2. Customizing SpringApplication .......................................................................... 53
23.3. Fluent Builder API ............................................................................................ 53
23.4. Application Events and Listeners ...................................................................... 54
23.5. Web Environment ............................................................................................. 55
23.6. Accessing Application Arguments ...................................................................... 55
23.7. Using the ApplicationRunner or CommandLineRunner ....................................... 55
23.8. Application Exit ................................................................................................ 56
23.9. 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
Loading YAML .................................................................................................. 62
Exposing YAML as Properties in the Spring Environment .................................... 63
Spring Boot Reference Guide
2.0.0.BUILD-SNAPSHOT Spring Boot iv
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 ....................................................................................... 69
@ConfigurationProperties Validation .................................................................. 70
@ConfigurationProperties vs. @Value ............................................................... 71
25. Profiles ....................................................................................................................... 72
25.1. Adding Active Profiles ...................................................................................... 72
25.2. Programmatically Setting Profiles ...................................................................... 73
25.3. Profile-specific Configuration Files ..................................................................... 73
26. Logging ...................................................................................................................... 74
26.1. Log Format ...................................................................................................... 74
26.2. Console Output ................................................................................................ 74
Color-coded Output ........................................................................................... 75
26.3. File Output ....................................................................................................... 76
26.4. Log Levels ....................................................................................................... 76
26.5. Custom Log Configuration ................................................................................ 77
26.6. Logback Extensions ......................................................................................... 79
Profile-specific Configuration ............................................................................. 79
Environment Properties ..................................................................................... 79
27. Developing Web Applications ...................................................................................... 81
27.1. The ‘Spring Web MVC Framework’ ................................................................... 81
Spring MVC Auto-configuration .......................................................................... 81
HttpMessageConverters .................................................................................... 82
Custom JSON Serializers and Deserializers ....................................................... 82
MessageCodesResolver .................................................................................... 83
Static Content ................................................................................................... 83
Custom Favicon ................................................................................................ 85
ConfigurableWebBindingInitializer ...................................................................... 85
Template Engines ............................................................................................. 85
Error Handling .................................................................................................. 85
Custom Error Pages ................................................................................. 86
Mapping Error Pages outside of Spring MVC ............................................. 87
Error Handling on WebSphere Application Server ....................................... 87
Spring HATEOAS ............................................................................................. 88
CORS Support .................................................................................................. 88
27.2. The ‘Spring WebFlux Framework’ ..................................................................... 88
Spring WebFlux Auto-configuration .................................................................... 89
HTTP Codecs with HttpMessageReaders and HttpMessageWriters ..................... 90
Static Content ................................................................................................... 90
Template Engines ............................................................................................. 91
Error Handling .................................................................................................. 91
Custom Error Pages ................................................................................. 92
27.3. JAX-RS and Jersey .......................................................................................... 92
27.4. Embedded Servlet Container Support ................................................................ 93
Servlets, Filters, and listeners ............................................................................ 94
Registering Servlets, Filters, and Listeners as Spring Beans ........................ 94
Spring Boot Reference Guide
2.0.0.BUILD-SNAPSHOT Spring Boot v
Servlet Context Initialization .............................................................................. 94
Scanning for Servlets, Filters, and listeners ................................................ 94
The ServletWebServerApplicationContext .......................................................... 94
Customizing Embedded Servlet Containers ........................................................ 95
Programmatic Customization ..................................................................... 95
Customizing ConfigurableServletWebServerFactory Directly ........................ 96
JSP Limitations ................................................................................................. 96
28. Security ...................................................................................................................... 97
28.1. OAuth2 ............................................................................................................ 97
Client ................................................................................................................ 97
28.2. Actuator Security .............................................................................................. 99
29. Working with SQL Databases .................................................................................... 100
29.1. Configure a DataSource ................................................................................. 100
Embedded Database Support .......................................................................... 100
Connection to a Production Database .............................................................. 101
Connection to a JNDI DataSource ................................................................... 102
29.2. Using JdbcTemplate ....................................................................................... 102
29.3. JPA and ‘Spring Data’ .................................................................................... 103
Entity Classes ................................................................................................. 103
Spring Data JPA Repositories ......................................................................... 104
Creating and Dropping JPA Databases ............................................................ 105
Open EntityManager in View ........................................................................... 105
29.4. Using H2’s Web Console ................................................................................ 105
Changing the H2 Console’s Path ..................................................................... 106
29.5. Using jOOQ ................................................................................................... 106
Code Generation ............................................................................................. 106
Using DSLContext ........................................................................................... 106
jOOQ SQL Dialect .......................................................................................... 107
Customizing jOOQ .......................................................................................... 107
30. Working with NoSQL Technologies ............................................................................ 108
30.1. Redis ............................................................................................................. 108
Connecting to Redis ........................................................................................ 108
30.2. MongoDB ....................................................................................................... 109
Connecting to a MongoDB Database ............................................................... 109
MongoTemplate .............................................................................................. 110
Spring Data MongoDB Repositories ................................................................. 110
Embedded Mongo ........................................................................................... 111
30.3. Neo4j ............................................................................................................. 111
Connecting to a Neo4j Database ..................................................................... 111
Using the Embedded Mode ............................................................................. 112
Neo4jSession .................................................................................................. 112
Spring Data Neo4j Repositories ....................................................................... 112
Repository Example ........................................................................................ 112
30.4. Gemfire .......................................................................................................... 113
30.5. Solr ................................................................................................................ 113
Connecting to Solr .......................................................................................... 113
Spring Data Solr Repositories .......................................................................... 113
30.6. Elasticsearch .................................................................................................. 114
Connecting to Elasticsearch by Using Jest ....................................................... 114
Connecting to Elasticsearch by Using Spring Data ............................................ 114
