Spring Boot Reference Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 378 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Spring Boot Reference Guide
1.5.7.RELEASE
Phillip Webb , Dave Syer , Josh Long , Stéphane Nicoll , Rob Winch , Andy
Wilkinson , Marcel Overdijk , Christian Dupuis , Sébastien Deleuze , Michael Simons
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
1.5.7.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 ............................................................................... 24
Using Spring Boot without the parent POM ........................................................ 25
Changing the Java version ................................................................................ 26
Using the Spring Boot Maven plugin .................................................................. 26
13.3. Gradle .............................................................................................................. 26
13.4. Ant ................................................................................................................... 27
13.5. Starters ............................................................................................................ 28
14. Structuring your code .................................................................................................. 33
14.1. Using the “default” package .............................................................................. 33
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot iii
14.2. Locating the main application class ................................................................... 33
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 .................................................................. 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
Remote debug tunnel ........................................................................................ 47
21. Packaging your application for production ..................................................................... 49
22. What to read next ....................................................................................................... 50
IV. Spring Boot features ............................................................................................................ 51
23. SpringApplication ......................................................................................................... 52
23.1. Startup failure ................................................................................................... 52
23.2. Customizing the Banner .................................................................................... 53
23.3. Customizing SpringApplication .......................................................................... 54
23.4. Fluent builder API ............................................................................................. 54
23.5. Application events and listeners ........................................................................ 55
23.6. Web environment ............................................................................................. 55
23.7. Accessing application arguments ....................................................................... 56
23.8. Using the ApplicationRunner or CommandLineRunner ........................................ 56
23.9. Application exit ................................................................................................. 57
23.10. Admin features ............................................................................................... 57
24. Externalized Configuration ........................................................................................... 59
24.1. Configuring random values ............................................................................... 60
24.2. Accessing command line properties .................................................................. 60
24.3. Application property files ................................................................................... 61
24.4. Profile-specific properties .................................................................................. 62
24.5. Placeholders in properties ................................................................................. 63
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot iv
24.6. Using YAML instead of Properties ..................................................................... 63
Loading YAML .................................................................................................. 63
Exposing YAML as properties in the Spring Environment .................................... 64
Multi-profile YAML documents ........................................................................... 64
YAML shortcomings .......................................................................................... 65
Merging YAML lists ........................................................................................... 65
24.7. Type-safe Configuration Properties .................................................................... 66
Third-party configuration .................................................................................... 69
Relaxed binding ................................................................................................ 69
Properties conversion ........................................................................................ 70
@ConfigurationProperties Validation .................................................................. 70
@ConfigurationProperties vs. @Value ............................................................... 71
25. Profiles ....................................................................................................................... 72
25.1. Adding active profiles ....................................................................................... 72
25.2. Programmatically setting profiles ....................................................................... 72
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 .......................................................................................... 78
Profile-specific configuration .............................................................................. 79
Environment properties ...................................................................................... 79
27. Developing web applications ........................................................................................ 80
27.1. The ‘Spring Web MVC framework’ .................................................................... 80
Spring MVC auto-configuration .......................................................................... 80
HttpMessageConverters .................................................................................... 81
Custom JSON Serializers and Deserializers ....................................................... 81
MessageCodesResolver .................................................................................... 82
Static Content ................................................................................................... 82
Custom Favicon ................................................................................................ 84
ConfigurableWebBindingInitializer ...................................................................... 84
Template engines .............................................................................................. 84
Error Handling .................................................................................................. 84
Custom error pages .................................................................................. 85
Mapping error pages outside of Spring MVC .............................................. 86
Error Handling on WebSphere Application Server ....................................... 86
Spring HATEOAS .............................................................................................. 87
CORS support .................................................................................................. 87
27.2. JAX-RS and Jersey .......................................................................................... 87
27.3. Embedded servlet container support .................................................................. 88
Servlets, Filters, and listeners ............................................................................ 89
Registering Servlets, Filters, and listeners as Spring beans ......................... 89
Servlet Context Initialization ............................................................................... 89
Scanning for Servlets, Filters, and listeners ................................................ 89
The EmbeddedWebApplicationContext ............................................................... 89
Customizing embedded servlet containers .......................................................... 90
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot v
Programmatic customization ...................................................................... 90
Customizing ConfigurableEmbeddedServletContainer directly ...................... 91
JSP limitations .................................................................................................. 91
28. Security ...................................................................................................................... 92
28.1. OAuth2 ............................................................................................................ 93
Authorization Server .......................................................................................... 93
Resource Server ............................................................................................... 93
28.2. Token Type in User Info ................................................................................... 94
28.3. Customizing the User Info RestTemplate ........................................................... 94
Client ................................................................................................................ 95
Single Sign On ................................................................................................. 96
28.4. Actuator Security .............................................................................................. 97
29. Working with SQL databases ....................................................................................... 98
29.1. Configure a DataSource ................................................................................... 98
Embedded Database Support ............................................................................ 98
Connection to a production database ................................................................. 99
Connection to a JNDI DataSource ................................................................... 100
29.2. Using JdbcTemplate ....................................................................................... 100
29.3. JPA and ‘Spring Data’ .................................................................................... 101
Entity Classes ................................................................................................. 101
Spring Data JPA Repositories .......................................................................... 102
Creating and dropping JPA databases ............................................................. 103
Open EntityManager in View ........................................................................... 103
29.4. Using H2’s web console ................................................................................. 103
Changing the H2 console’s path ...................................................................... 103
Securing the H2 console ................................................................................. 104
29.5. Using jOOQ ................................................................................................... 104
Code Generation ............................................................................................. 104
Using DSLContext ........................................................................................... 104
Customizing jOOQ .......................................................................................... 105
30. Working with NoSQL technologies ............................................................................. 106
30.1. Redis ............................................................................................................. 106
Connecting to Redis ........................................................................................ 106
30.2. MongoDB ....................................................................................................... 106
Connecting to a MongoDB database ................................................................ 106
MongoTemplate .............................................................................................. 107
Spring Data MongoDB repositories .................................................................. 108
Embedded Mongo ........................................................................................... 108
30.3. Neo4j ............................................................................................................. 109
Connecting to a Neo4j database ...................................................................... 109
Using the embedded mode .............................................................................. 109
Neo4jSession .................................................................................................. 109
Spring Data Neo4j repositories ........................................................................ 110
Repository example ......................................................................................... 110
30.4. Gemfire .......................................................................................................... 110
30.5. Solr ................................................................................................................ 110
Connecting to Solr .......................................................................................... 111
Spring Data Solr repositories ........................................................................... 111
30.6. Elasticsearch .................................................................................................. 111
Connecting to Elasticsearch using Jest ............................................................ 111
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot vi
Connecting to Elasticsearch using Spring Data ................................................. 112
Spring Data Elasticsearch repositories ............................................................. 112
30.7. Cassandra ...................................................................................................... 112
Connecting to Cassandra ................................................................................ 113
Spring Data Cassandra repositories ................................................................. 113
30.8. Couchbase ..................................................................................................... 113
Connecting to Couchbase ................................................................................ 113
Spring Data Couchbase repositories ................................................................ 114
30.9. LDAP ............................................................................................................. 115
Connecting to an LDAP server ........................................................................ 115
Spring Data LDAP repositories ........................................................................ 115
Embedded in-memory LDAP server ................................................................. 115
31. Caching .................................................................................................................... 117
31.1. Supported cache providers ............................................................................. 118
Generic ........................................................................................................... 119
JCache (JSR-107) ........................................................................................... 119
EhCache 2.x ................................................................................................... 120
Hazelcast ........................................................................................................ 120
Infinispan ........................................................................................................ 120
Couchbase ...................................................................................................... 120
Redis .............................................................................................................. 121
Caffeine .......................................................................................................... 121
Guava (deprecated) ......................................................................................... 122
Simple ............................................................................................................ 122
None ............................................................................................................... 122
32. Messaging ................................................................................................................ 123
32.1. JMS ............................................................................................................... 123
ActiveMQ support ............................................................................................ 123
Artemis support ............................................................................................... 124
Using a JNDI ConnectionFactory ..................................................................... 124
Sending a message ........................................................................................ 124
Receiving a message ...................................................................................... 125
32.2. AMQP ............................................................................................................ 126
RabbitMQ support ........................................................................................... 126
Sending a message ........................................................................................ 126
Receiving a message ...................................................................................... 127
32.3. Apache Kafka Support .................................................................................... 128
Sending a Message ........................................................................................ 128
Receiving a Message ...................................................................................... 129
Additional Kafka Properties .............................................................................. 129
33. Calling REST services ............................................................................................... 131
33.1. RestTemplate customization ............................................................................ 131
34. Validation .................................................................................................................. 133
35. Sending email ........................................................................................................... 134
36. Distributed Transactions with JTA .............................................................................. 135
36.1. Using an Atomikos transaction manager .......................................................... 135
36.2. Using a Bitronix transaction manager .............................................................. 135
36.3. Using a Narayana transaction manager ........................................................... 136
36.4. Using a Java EE managed transaction manager .............................................. 136
36.5. Mixing XA and non-XA JMS connections ......................................................... 136
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot vii
36.6. Supporting an alternative embedded transaction manager ................................ 137
37. Hazelcast .................................................................................................................. 138
38. Spring Integration ...................................................................................................... 139
39. Spring Session .......................................................................................................... 140
40. Monitoring and management over JMX ...................................................................... 141
41. Testing ...................................................................................................................... 142
41.1. Test scope dependencies ............................................................................... 142
41.2. Testing Spring applications ............................................................................. 142
41.3. Testing Spring Boot applications ..................................................................... 143
Detecting test configuration .............................................................................. 143
Excluding test configuration ............................................................................. 144
Working with random ports .............................................................................. 144
Mocking and spying beans .............................................................................. 145
Auto-configured tests ....................................................................................... 146
Auto-configured JSON tests ............................................................................. 146
Auto-configured Spring MVC tests ................................................................... 147
Auto-configured Data JPA tests ....................................................................... 149
Auto-configured JDBC tests ............................................................................. 150
Auto-configured Data MongoDB tests ............................................................... 150
Auto-configured REST clients .......................................................................... 151
Auto-configured Spring REST Docs tests ......................................................... 152
Using Spock to test Spring Boot applications .................................................... 153
41.4. Test utilities .................................................................................................... 153
ConfigFileApplicationContextInitializer ............................................................... 153
EnvironmentTestUtils ....................................................................................... 154
OutputCapture ................................................................................................. 154
TestRestTemplate ........................................................................................... 154
42. WebSockets .............................................................................................................. 156
43. Web Services ............................................................................................................ 157
44. Creating your own auto-configuration ......................................................................... 158
44.1. Understanding auto-configured beans .............................................................. 158
44.2. Locating auto-configuration candidates ............................................................ 158
44.3. Condition annotations ..................................................................................... 158
Class conditions .............................................................................................. 159
Bean conditions .............................................................................................. 159
Property conditions .......................................................................................... 160
Resource conditions ........................................................................................ 160
Web application conditions .............................................................................. 160
SpEL expression conditions ............................................................................. 160
44.4. Creating your own starter ................................................................................ 160
Naming ........................................................................................................... 160
Autoconfigure module ...................................................................................... 161
Starter module ................................................................................................ 161
45. What to read next ..................................................................................................... 162
V. Spring Boot Actuator: Production-ready features .................................................................. 163
46. Enabling production-ready features ............................................................................ 164
47. Endpoints .................................................................................................................. 165
47.1. Customizing endpoints .................................................................................... 166
47.2. Hypermedia for actuator MVC endpoints .......................................................... 167
47.3. CORS support ................................................................................................ 167
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot viii
47.4. Adding custom endpoints ................................................................................ 167
47.5. Health information .......................................................................................... 168
47.6. Security with HealthIndicators ......................................................................... 168
Auto-configured HealthIndicators ...................................................................... 168
Writing custom HealthIndicators ....................................................................... 169
47.7. Application information .................................................................................... 170
Auto-configured InfoContributors ...................................................................... 170
Custom application info information .................................................................. 170
Git commit information ..................................................................................... 171
Build information ............................................................................................. 171
Writing custom InfoContributors ....................................................................... 171
48. Monitoring and management over HTTP .................................................................... 173
48.1. Accessing sensitive endpoints ......................................................................... 173
48.2. Customizing the management endpoint paths .................................................. 174
48.3. Customizing the management server port ........................................................ 174
48.4. Configuring management-specific SSL ............................................................. 175
48.5. Customizing the management server address .................................................. 175
48.6. Disabling HTTP endpoints ............................................................................... 175
48.7. HTTP health endpoint format and access restrictions ........................................ 176
49. Monitoring and management over JMX ...................................................................... 178
49.1. Customizing MBean names ............................................................................. 178
49.2. Disabling JMX endpoints ................................................................................. 178
49.3. Using Jolokia for JMX over HTTP ................................................................... 178
Customizing Jolokia ......................................................................................... 178
Disabling Jolokia ............................................................................................. 178
50. Monitoring and management using a remote shell (deprecated) ................................... 180
50.1. Connecting to the remote shell ........................................................................ 180
Remote shell credentials ................................................................................. 181
50.2. Extending the remote shell .............................................................................. 181
Remote shell commands ................................................................................. 181
Remote shell plugins ....................................................................................... 182
51. Loggers ..................................................................................................................... 183
51.1. Configure a Logger ......................................................................................... 183
52. Metrics ...................................................................................................................... 184
52.1. System metrics ............................................................................................... 184
52.2. DataSource metrics ........................................................................................ 185
52.3. Cache metrics ................................................................................................ 185
52.4. Tomcat session metrics .................................................................................. 186
52.5. Recording your own metrics ............................................................................ 186
52.6. Adding your own public metrics ....................................................................... 186
52.7. Special features with Java 8 ........................................................................... 187
52.8. Metric writers, exporters and aggregation ......................................................... 187
Example: Export to Redis ................................................................................ 188
Example: Export to Open TSDB ...................................................................... 188
Example: Export to Statsd ............................................................................... 189
Example: Export to JMX .................................................................................. 189
52.9. Aggregating metrics from multiple sources ....................................................... 190
52.10. Dropwizard Metrics ....................................................................................... 190
52.11. Message channel integration ......................................................................... 191
53. Auditing ..................................................................................................................... 192
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot ix
54. Tracing ..................................................................................................................... 193
54.1. Custom tracing ............................................................................................... 193
55. Process monitoring .................................................................................................... 194
55.1. Extend configuration ....................................................................................... 194
55.2. Programmatically ............................................................................................ 194
56. Cloud Foundry support .............................................................................................. 195
56.1. Disabling extended Cloud Foundry actuator support ......................................... 195
56.2. Cloud Foundry self signed certificates ............................................................. 195
56.3. Custom security configuration ......................................................................... 195
57. What to read next ..................................................................................................... 196
VI. Deploying Spring Boot applications ..................................................................................... 197
58. Deploying to the cloud ............................................................................................... 198
58.1. Cloud Foundry ................................................................................................ 198
Binding to services .......................................................................................... 199
58.2. Heroku ........................................................................................................... 199
58.3. OpenShift ....................................................................................................... 201
58.4. Amazon Web Services (AWS) ......................................................................... 201
AWS Elastic Beanstalk .................................................................................... 202
Using the Tomcat platform ....................................................................... 202
Using the Java SE platform ..................................................................... 202
Best practices ......................................................................................... 202
Summary ........................................................................................................ 202
58.5. Boxfuse and Amazon Web Services ................................................................ 202
58.6. Google Cloud ................................................................................................. 203
59. Installing Spring Boot applications .............................................................................. 205
59.1. Supported operating systems .......................................................................... 205
59.2. Unix/Linux services ......................................................................................... 205
Installation as an init.d service (System V) ....................................................... 205
Securing an init.d service ........................................................................ 206
Installation as a systemd service ..................................................................... 207
Customizing the startup script .......................................................................... 207
Customizing script when it’s written .......................................................... 208
Customizing script when it runs ............................................................... 209
59.3. Microsoft Windows services ............................................................................ 210
60. What to read next ..................................................................................................... 211
VII. Spring Boot CLI ................................................................................................................ 212
61. Installing the CLI ....................................................................................................... 213
62. Using the CLI ............................................................................................................ 214
62.1. Running applications using the CLI ................................................................. 214
Deduced “grab” dependencies ......................................................................... 215
Deduced “grab” coordinates ............................................................................. 216
Default import statements ................................................................................ 216
Automatic main method ................................................................................... 216
Custom dependency management ................................................................... 216
62.2. Testing your code ........................................................................................... 217
62.3. Applications with multiple source files .............................................................. 217
62.4. Packaging your application ............................................................................. 217
62.5. Initialize a new project .................................................................................... 218
62.6. Using the embedded shell .............................................................................. 218
62.7. Adding extensions to the CLI .......................................................................... 219
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot x
63. Developing application with the Groovy beans DSL ..................................................... 220
64. Configuring the CLI with settings.xml .......................................................................... 221
65. What to read next ..................................................................................................... 222
VIII. Build tool plugins ............................................................................................................. 223
66. Spring Boot Maven plugin .......................................................................................... 224
66.1. Including the plugin ........................................................................................ 224
66.2. Packaging executable jar and war files ............................................................ 225
67. Spring Boot Gradle plugin .......................................................................................... 226
67.1. Including the plugin ........................................................................................ 226
67.2. Gradle dependency management .................................................................... 226
67.3. Packaging executable jar and war files ............................................................ 226
67.4. Running a project in-place .............................................................................. 227
67.5. Spring Boot plugin configuration ...................................................................... 227
67.6. Repackage configuration ................................................................................. 228
67.7. Repackage with custom Gradle configuration ................................................... 229
Configuration options ....................................................................................... 229
Available layouts ............................................................................................. 230
Using a custom layout ..................................................................................... 230
67.8. Understanding how the Gradle plugin works .................................................... 231
67.9. Publishing artifacts to a Maven repository using Gradle .................................... 231
Configuring Gradle to produce a pom that inherits dependency management ...... 231
Configuring Gradle to produce a pom that imports dependency management ...... 232
68. Spring Boot AntLib module ........................................................................................ 233
68.1. Spring Boot Ant tasks ..................................................................................... 233
spring-boot:exejar ............................................................................................ 233
Examples ........................................................................................................ 233
68.2. spring-boot:findmainclass ................................................................................ 234
Examples ........................................................................................................ 234
69. Supporting other build systems .................................................................................. 235
69.1. Repackaging archives ..................................................................................... 235
69.2. Nested libraries .............................................................................................. 235
69.3. Finding a main class ....................................................................................... 235
69.4. Example repackage implementation ................................................................ 235
70. What to read next ..................................................................................................... 236
IX. ‘How-to’ guides .................................................................................................................. 237
71. Spring Boot application .............................................................................................. 238
71.1. Create your own FailureAnalyzer ..................................................................... 238
71.2. Troubleshoot auto-configuration ....................................................................... 238
71.3. Customize the Environment or ApplicationContext before it starts ...................... 239
71.4. Build an ApplicationContext hierarchy (adding a parent or root context) .............. 240
71.5. Create a non-web application .......................................................................... 240
72. Properties & configuration .......................................................................................... 241
72.1. Automatically expand properties at build time ................................................... 241
Automatic property expansion using Maven ...................................................... 241
Automatic property expansion using Gradle ...................................................... 242
72.2. Externalize the configuration of SpringApplication ............................................. 242
72.3. Change the location of external properties of an application .............................. 243
72.4. Use ‘short’ command line arguments ............................................................... 243
72.5. Use YAML for external properties .................................................................... 244
72.6. Set the active Spring profiles .......................................................................... 244
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot xi
72.7. Change configuration depending on the environment ........................................ 244
72.8. Discover built-in options for external properties ................................................ 245
73. Embedded servlet containers ..................................................................................... 246
73.1. Add a Servlet, Filter or Listener to an application .............................................. 246
Add a Servlet, Filter or Listener using a Spring bean ......................................... 246
Disable registration of a Servlet or Filter ................................................... 246
Add Servlets, Filters, and Listeners using classpath scanning ............................ 246
73.2. Change the HTTP port ................................................................................... 247
73.3. Use a random unassigned HTTP port .............................................................. 247
73.4. Discover the HTTP port at runtime .................................................................. 247
73.5. Configure SSL ................................................................................................ 247
73.6. Configure Access Logging .............................................................................. 248
73.7. Use behind a front-end proxy server ................................................................ 248
Customize Tomcat’s proxy configuration ........................................................... 249
73.8. Configure Tomcat ........................................................................................... 249
73.9. Enable Multiple Connectors with Tomcat ......................................................... 249
73.10. Use Tomcat’s LegacyCookieProcessor .......................................................... 250
73.11. Use Jetty instead of Tomcat .......................................................................... 250
73.12. Configure Jetty ............................................................................................. 251
73.13. Use Undertow instead of Tomcat ................................................................... 251
73.14. Configure Undertow ...................................................................................... 252
73.15. Enable Multiple Listeners with Undertow ........................................................ 252
73.16. Use Tomcat 7.x or 8.0 .................................................................................. 252
Use Tomcat 7.x or 8.0 with Maven .................................................................. 252
Use Tomcat 7.x or 8.0 with Gradle .................................................................. 253
73.17. Use Jetty 9.2 ................................................................................................ 253
Use Jetty 9.2 with Maven ................................................................................ 253
Use Jetty 9.2 with Gradle ................................................................................ 253
73.18. Use Jetty 8 ................................................................................................... 253
Use Jetty 8 with Maven ................................................................................... 254
Use Jetty 8 with Gradle ................................................................................... 254
73.19. Create WebSocket endpoints using @ServerEndpoint .................................... 254
73.20. Enable HTTP response compression ............................................................. 255
74. Spring MVC .............................................................................................................. 256
74.1. Write a JSON REST service ........................................................................... 256
74.2. Write an XML REST service ........................................................................... 256
74.3. Customize the Jackson ObjectMapper ............................................................. 256
74.4. Customize the @ResponseBody rendering ...................................................... 258
74.5. Handling Multipart File Uploads ....................................................................... 258
74.6. Switch off the Spring MVC DispatcherServlet ................................................... 258
74.7. Switch off the Default MVC configuration ......................................................... 259
74.8. Customize ViewResolvers ............................................................................... 259
74.9. Use Thymeleaf 3 ............................................................................................ 260
75. HTTP clients ............................................................................................................. 261
75.1. Configure RestTemplate to use a proxy ........................................................... 261
76. Logging ..................................................................................................................... 262
76.1. Configure Logback for logging ......................................................................... 262
Configure logback for file only output ............................................................... 263
76.2. Configure Log4j for logging ............................................................................. 263
Use YAML or JSON to configure Log4j 2 ......................................................... 264
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot xii
77. Data Access ............................................................................................................. 265
77.1. Configure a custom DataSource ...................................................................... 265
77.2. Configure Two DataSources ........................................................................... 267
77.3. Use Spring Data repositories .......................................................................... 268
77.4. Separate @Entity definitions from Spring configuration ..................................... 268
77.5. Configure JPA properties ................................................................................ 268
77.6. Configure Hibernate Naming Strategy .............................................................. 269
77.7. Use a custom EntityManagerFactory ............................................................... 269
77.8. Use Two EntityManagers ................................................................................ 269
77.9. Use a traditional persistence.xml ..................................................................... 270
77.10. Use Spring Data JPA and Mongo repositories ................................................ 270
77.11. Expose Spring Data repositories as REST endpoint ........................................ 271
77.12. Configure a component that is used by JPA ................................................... 271
78. Database initialization ................................................................................................ 272
78.1. Initialize a database using JPA ....................................................................... 272
78.2. Initialize a database using Hibernate ............................................................... 272
78.3. Initialize a database using Spring JDBC .......................................................... 272
78.4. Initialize a Spring Batch database ................................................................... 273
78.5. Use a higher-level database migration tool ....................................................... 273
Execute Flyway database migrations on startup ................................................ 273
Execute Liquibase database migrations on startup ............................................ 274
79. Messaging ................................................................................................................ 275
79.1. Disable transacted JMS session ...................................................................... 275
80. Batch applications ..................................................................................................... 276
80.1. Execute Spring Batch jobs on startup .............................................................. 276
81. Actuator .................................................................................................................... 277
81.1. Change the HTTP port or address of the actuator endpoints ............................. 277
81.2. Customize the ‘whitelabel’ error page .............................................................. 277
81.3. Actuator and Jersey ........................................................................................ 277
82. Security ..................................................................................................................... 278
82.1. Switch off the Spring Boot security configuration .............................................. 278
82.2. Change the AuthenticationManager and add user accounts .............................. 278
82.3. Enable HTTPS when running behind a proxy server ......................................... 278
83. Hot swapping ............................................................................................................ 280
83.1. Reload static content ...................................................................................... 280
83.2. Reload templates without restarting the container ............................................. 280
Thymeleaf templates ....................................................................................... 280
FreeMarker templates ...................................................................................... 280
Groovy templates ............................................................................................ 280
83.3. Fast application restarts .................................................................................. 280
83.4. Reload Java classes without restarting the container ........................................ 281
Configuring Spring Loaded for use with Maven ................................................. 281
Configuring Spring Loaded for use with Gradle and IntelliJ IDEA ........................ 281
84. Build ......................................................................................................................... 283
84.1. Generate build information .............................................................................. 283
84.2. Generate git information .................................................................................. 283
84.3. Customize dependency versions ..................................................................... 284
84.4. Create an executable JAR with Maven ............................................................ 284
84.5. Use a Spring Boot application as a dependency ............................................... 285
84.6. Extract specific libraries when an executable jar runs ....................................... 285
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot xiii
84.7. Create a non-executable JAR with exclusions .................................................. 286
84.8. Remote debug a Spring Boot application started with Maven ............................. 287
84.9. Remote debug a Spring Boot application started with Gradle ............................. 287
84.10. Build an executable archive from Ant without using spring-boot-antlib ............... 288
84.11. How to use Java 6 ....................................................................................... 288
Embedded servlet container compatibility ......................................................... 289
Jackson .......................................................................................................... 289
JTA API compatibility ...................................................................................... 289
85. Traditional deployment ............................................................................................... 290
85.1. Create a deployable war file ........................................................................... 290
85.2. Create a deployable war file for older servlet containers .................................... 291
85.3. Convert an existing application to Spring Boot .................................................. 291
85.4. Deploying a WAR to WebLogic ....................................................................... 293
85.5. Deploying a WAR in an Old (Servlet 2.5) Container .......................................... 293
X. Appendices ......................................................................................................................... 295
A. Common application properties ................................................................................... 296
B. Configuration meta-data .............................................................................................. 318
B.1. Meta-data format .............................................................................................. 318
Group Attributes .............................................................................................. 319
Property Attributes ........................................................................................... 320
Hint Attributes ................................................................................................. 322
Repeated meta-data items ............................................................................... 322
B.2. Providing manual hints ..................................................................................... 323
Value hint ....................................................................................................... 323
Value provider ................................................................................................. 323
Any ......................................................................................................... 324
Class reference ....................................................................................... 325
Handle As ............................................................................................... 325
Logger name .......................................................................................... 326
Spring bean reference ............................................................................. 327
Spring profile name ................................................................................. 328
B.3. Generating your own meta-data using the annotation processor .......................... 328
Nested properties ............................................................................................ 329
Adding additional meta-data ............................................................................ 329
C. Auto-configuration classes ........................................................................................... 331
C.1. From the “spring-boot-autoconfigure” module .................................................... 331
C.2. From the “spring-boot-actuator” module ............................................................ 334
D. Test auto-configuration annotations ............................................................................. 336
E. The executable jar format ........................................................................................... 338
E.1. Nested JARs ................................................................................................... 338
The executable jar file structure ....................................................................... 338
The executable war file structure ..................................................................... 338
E.2. Spring Boot’s “JarFile” class ............................................................................. 339
Compatibility with the standard Java “JarFile” ................................................... 339
E.3. Launching executable jars ................................................................................ 339
Launcher manifest ........................................................................................... 340
Exploded archives ........................................................................................... 340
E.4. PropertiesLauncher Features ............................................................................ 340
E.5. Executable jar restrictions ................................................................................. 342
Zip entry compression ..................................................................................... 342
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot xiv
System ClassLoader ....................................................................................... 342
E.6. Alternative single jar solutions .......................................................................... 342
F. Dependency versions .................................................................................................. 343
Part I. Spring Boot Documentation
This section provides a brief overview of Spring Boot reference documentation. Think of it as map for
the rest of the document. You can read this reference guide in a linear fashion, or you can skip sections
if something doesn’t interest you.
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 2
1. About the documentation
The Spring Boot reference guide is available as html, pdf and epub documents. The latest copy is
available at docs.spring.io/spring-boot/docs/current/reference.
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
1.5.7.RELEASE Spring Boot 3
2. Getting help
Having trouble with Spring Boot, We’d like to help!
• Try the How-to’s — they provide solutions to the most common questions.
• Learn the Spring basics — Spring Boot builds on many other Spring projects, check the spring.io web-
site for a wealth of reference documentation. If you are just starting out with Spring, try one of the
guides.
• Ask a question - we monitor stackoverflow.com for questions tagged with spring-boot.
• Report bugs with Spring Boot at 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 just want to improve them, please get involved.
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 4
3. First steps
If you’re just getting started with Spring Boot, or 'Spring' in general, this is the place to start!
•From scratch: Overview | Requirements | Installation
•Tutorial: Part 1 | Part 2
•Running your example: Part 1 | Part 2
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 5
4. Working with Spring Boot
Ready to actually start using Spring Boot? We’ve got you covered.
•Build systems: Maven | Gradle | Ant | Starters
•Best practices: Code Structure | @Configuration | @EnableAutoConfiguration | Beans and
Dependency Injection
•Running your code IDE | Packaged | Maven | Gradle
•Packaging your app: Production jars
•Spring Boot CLI: Using the CLI
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 6
5. Learning about Spring Boot features
Need more details about Spring Boot’s core features? This is for you!
•Core Features: SpringApplication | External Configuration | Profiles | Logging
•Web Applications: MVC | Embedded Containers
•Working with data: SQL | NO-SQL
•Messaging: Overview | JMS
•Testing: Overview | Boot Applications | Utils
•Extending: Auto-configuration | @Conditions
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 7
6. Moving to production
When you’re ready to push your Spring Boot application to production, we’ve got some tricks that you
might like!
•Management endpoints: Overview | Customization
•Connection options: HTTP | JMX | SSH
•Monitoring: Metrics | Auditing | Tracing | Process
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 8
7. Advanced topics
Lastly, we have a few topics for the more advanced user.
•Deploy Spring Boot Applications: Cloud Deployment | OS Service
•Build tool plugins: Maven | Gradle
•Appendix: Application Properties | Auto-configuration classes | Executable Jars
Part II. Getting started
If you’re just getting started with Spring Boot, or 'Spring' in general, this is the section for you! Here we
answer the basic “what?”, “how?” and “why?” questions. You’ll find a gentle introduction to Spring Boot
along with installation instructions. We’ll then build our first Spring Boot application, discussing some
core principles as we go.
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 10
8. Introducing Spring Boot
Spring Boot makes it easy to create stand-alone, production-grade Spring based Applications that you
can “just run”. We take an opinionated view of the Spring platform and third-party libraries so you can
get started with minimum fuss. Most Spring Boot applications need very little Spring configuration.
You can use Spring Boot to create Java applications that can be started using java -jar or more
traditional war deployments. We also provide a command line tool that runs “spring scripts”.
Our primary goals are:
• Provide a radically faster and widely accessible getting started experience for all Spring development.
• Be opinionated out of the box, but get out of the way quickly as requirements start to diverge from
the defaults.
• Provide a range of non-functional features that are common to large classes of projects (e.g.
embedded servers, security, metrics, health checks, externalized configuration).
• Absolutely no code generation and no requirement for XML configuration.
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 11
9. System Requirements
By default, Spring Boot 1.5.7.RELEASE requires Java 7 and Spring Framework 4.3.11.RELEASE or
above. You can use Spring Boot with Java 6 with some additional configuration. See Section 84.11,
“How to use Java 6” for more details. Explicit build support is provided for Maven (3.2+), and Gradle
2 (2.9 or later) and 3.
Tip
Although you can use Spring Boot with Java 6 or 7, we generally recommend Java 8 if at all
possible.
9.1 Servlet containers
The following embedded servlet containers are supported out of the box:
Name Servlet Version Java Version
Tomcat 8 3.1 Java 7+
Tomcat 7 3.0 Java 6+
Jetty 9.3 3.1 Java 8+
Jetty 9.2 3.1 Java 7+
Jetty 8 3.0 Java 6+
Undertow 1.3 3.1 Java 7+
You can also deploy Spring Boot applications to any Servlet 3.0+ compatible container.
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 12
10. Installing Spring Boot
Spring Boot can be used with “classic” Java development tools or installed as a command line tool.
Regardless, you will need Java SDK v1.6 or higher. You should check your current Java installation
before you begin:
$ java -version
If you are new to Java development, or if you just want to experiment with Spring Boot you might want
to try the Spring Boot CLI first, otherwise, read on for “classic” installation instructions.
Tip
Although Spring Boot is compatible with Java 1.6, if possible, you should consider using the latest
version of Java.
10.1 Installation instructions for the Java developer
You can use Spring Boot in the same way as any standard Java library. Simply include the appropriate
spring-boot-*.jar files on your classpath. Spring Boot does not require any special tools
integration, so you can use any IDE or text editor; and there is nothing special about a Spring Boot
application, so you can run and debug as you would any other Java program.
Although you could just copy Spring Boot jars, we generally recommend that you use a build tool that
supports dependency management (such as Maven or Gradle).
Maven installation
Spring Boot is compatible with Apache Maven 3.2 or above. If you don’t already have Maven installed
you can follow the instructions at maven.apache.org.
Tip
On many operating systems Maven can be installed via a package manager. If you’re an OSX
Homebrew user try brew install maven. Ubuntu users can run sudo apt-get install
maven.
Spring Boot dependencies use the org.springframework.boot groupId. Typically your Maven
POM file will inherit from the spring-boot-starter-parent project and declare dependencies to
one or more “Starters”. Spring Boot also provides an optional Maven plugin to create executable jars.
Here is a typical pom.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 13
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.7.RELEASE</version>
</parent>
<!-- Add typical dependencies for a web application -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<!-- Package as an executable jar -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
Tip
The spring-boot-starter-parent is a great way to use Spring Boot, but it might not be
suitable all of the time. Sometimes you may need to inherit from a different parent POM, or you
might just not like our default settings. See the section called “Using Spring Boot without the parent
POM” for an alternative solution that uses an import scope.
Gradle installation
Spring Boot is compatible with Gradle 2 (2.9 or later) and Gradle 3. If you don’t already have Gradle
installed you can follow the instructions at www.gradle.org/.
Spring Boot dependencies can be declared using the org.springframework.boot group. Typically
your project will declare dependencies to one or more “Starters”. Spring Boot provides a useful Gradle
plugin that can be used to simplify dependency declarations and to create executable jars.
Gradle Wrapper
The Gradle Wrapper provides a nice way of “obtaining” Gradle when you need to build a project.
It’s a small script and library that you commit alongside your code to bootstrap the build process.
See docs.gradle.org/2.14.1/userguide/gradle_wrapper.html for details.
Here is a typical build.gradle file:
plugins {
id 'org.springframework.boot' version '1.5.7.RELEASE'
id 'java'
}
jar {
baseName = 'myproject'
version = '0.0.1-SNAPSHOT'
}
repositories {
jcenter()
}
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 14
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
}
10.2 Installing the Spring Boot CLI
The Spring Boot CLI is a command line tool that can be used if you want to quickly prototype with Spring.
It allows you to run Groovy scripts, which means that you have a familiar Java-like syntax, without so
much boilerplate code.
You don’t need to use the CLI to work with Spring Boot but it’s definitely the quickest way to get a Spring
application off the ground.
Manual installation
You can download the Spring CLI distribution from the Spring software repository:
•spring-boot-cli-1.5.7.RELEASE-bin.zip
•spring-boot-cli-1.5.7.RELEASE-bin.tar.gz
Cutting edge snapshot distributions are also available.
Once downloaded, follow the INSTALL.txt instructions from the unpacked archive. In summary: there
is a spring script (spring.bat for Windows) in a bin/ directory in the .zip file, or alternatively you
can use java -jar with the .jar file (the script helps you to be sure that the classpath is set correctly).
Installation with SDKMAN!
SDKMAN! (The Software Development Kit Manager) can be used for managing multiple versions of
various binary SDKs, including Groovy and the Spring Boot CLI. Get SDKMAN! from sdkman.io and
install Spring Boot with
$ sdk install springboot
$ spring --version
Spring Boot v1.5.7.RELEASE
If you are developing features for the CLI and want easy access to the version you just built, follow
these extra instructions.
$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-1.5.7.RELEASE-
bin/spring-1.5.7.RELEASE/
$ sdk default springboot dev
$ spring --version
Spring CLI v1.5.7.RELEASE
This will install a local instance of spring called the dev instance. It points at your target build location,
so every time you rebuild Spring Boot, spring will be up-to-date.
You can see it by doing this:
$ sdk ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 1.5.7.RELEASE
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 15
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
OSX Homebrew installation
If you are on a Mac and using Homebrew, all you need to do to install the Spring Boot CLI is:
$ brew tap pivotal/tap
$ brew install springboot
Homebrew will install spring to /usr/local/bin.
Note
If you don’t see the formula, your installation of brew might be out-of-date. Just execute brew
update and try again.
MacPorts installation
If you are on a Mac and using MacPorts, all you need to do to install the Spring Boot CLI is:
$ sudo port install spring-boot-cli
Command-line completion
Spring Boot CLI ships with scripts that provide command completion for BASH and zsh shells. You can
source the script (also named spring) in any shell, or put it in your personal or system-wide bash
completion initialization. On a Debian system the system-wide scripts are in /shell-completion/
bash and all scripts in that directory are executed when a new shell starts. To run the script manually,
e.g. if you have installed using SDKMAN!
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
grab help jar run test version
Note
If you install Spring Boot CLI using Homebrew or MacPorts, the command-line completion scripts
are automatically registered with your shell.
Quick start Spring CLI example
Here’s a really simple web application that you can use to test your installation. Create a file called
app.groovy:
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
"Hello World!"
}
}
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 16
Then simply run it from a shell:
$ spring run app.groovy
Note
It will take some time when you first run the application as dependencies are downloaded.
Subsequent runs will be much quicker.
Open localhost:8080 in your favorite web browser and you should see the following output:
Hello World!
10.3 Upgrading from an earlier version of Spring Boot
If you are upgrading from an earlier release of Spring Boot check the “release notes” hosted on the
project wiki. You’ll find upgrade instructions along with a list of “new and noteworthy” features for each
release.
To upgrade an existing CLI installation use the appropriate package manager command (for example
brew upgrade) or, if you manually installed the CLI, follow the standard instructions remembering to
update your PATH environment variable to remove any older references.
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 17
11. Developing your first Spring Boot application
Let’s develop a simple “Hello World!” web application in Java that highlights some of Spring Boot’s key
features. We’ll use Maven to build this project since most IDEs support it.
Tip
The spring.io web site contains many “Getting Started” guides that use Spring Boot. If you’re
looking to solve a specific problem; check there first.
You can shortcut the steps below by going to start.spring.io and choosing the web starter from
the dependencies searcher. This will automatically generate a new project structure so that you
can start coding right away. Check the documentation for more details.
Before we begin, open a terminal to check that you have valid versions of Java and Maven installed.
$ java -version
java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)
$ mvn -v
Apache Maven 3.2.3 (33f8c3e1027c3ddde99d3cdebad2656a31e8fdf4; 2014-08-11T13:58:10-07:00)
Maven home: /Users/user/tools/apache-maven-3.1.1
Java version: 1.7.0_51, vendor: Oracle Corporation
Note
This sample needs to be created in its own folder. Subsequent instructions assume that you have
created a suitable folder and that it is your “current directory”.
11.1 Creating the POM
We need to start by creating a Maven pom.xml file. The pom.xml is the recipe that will be used to build
your project. Open your favorite text editor and add the following:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.7.RELEASE</version>
</parent>
<!-- Additional lines to be added here... -->
</project>
This should give you a working build, you can test it out by running mvn package (you can ignore the
“jar will be empty - no content was marked for inclusion!” warning for now).
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 18
Note
At this point you could import the project into an IDE (most modern Java IDE’s include built-in
support for Maven). For simplicity, we will continue to use a plain text editor for this example.
11.2 Adding classpath dependencies
Spring Boot provides a number of “Starters” that make easy to add jars to your classpath. Our sample
application has already used spring-boot-starter-parent in the parent section of the POM.
The spring-boot-starter-parent is a special starter that provides useful Maven defaults. It
also provides a dependency-management section so that you can omit version tags for “blessed”
dependencies.
Other “Starters” simply provide dependencies that you are likely to need when developing a specific
type of application. Since we are developing a web application, we will add a spring-boot-starter-
web dependency — but before that, let’s look at what we currently have.
$ mvn dependency:tree
[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT
The mvn dependency:tree command prints a tree representation of your project dependencies.
You can see that spring-boot-starter-parent provides no dependencies by itself. Let’s edit our
pom.xml and add the spring-boot-starter-web dependency just below the parent section:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
If you run mvn dependency:tree again, you will see that there are now a number of additional
dependencies, including the Tomcat web server and Spring Boot itself.
11.3 Writing the code
To finish our application we need to create a single Java file. Maven will compile sources from src/
main/java by default so you need to create that folder structure, then add a file named src/main/
java/Example.java:
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.stereotype.*;
import org.springframework.web.bind.annotation.*;
@RestController
@EnableAutoConfiguration
public class Example {
@RequestMapping("/")
String home() {
return "Hello World!";
}
public static void main(String[] args) throws Exception {
SpringApplication.run(Example.class, args);
}
}
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 19
Although there isn’t much code here, quite a lot is going on. Let’s step through the important parts.
The @RestController and @RequestMapping annotations
The first annotation on our Example class is @RestController. This is known as a stereotype
annotation. It provides hints for people reading the code, and for Spring, that the class plays a specific
role. In this case, our class is a web @Controller so Spring will consider it when handling incoming
web requests.
The @RequestMapping annotation provides “routing” information. It is telling Spring that any HTTP
request with the path “/” should be mapped to the home method. The @RestController annotation
tells Spring to render the resulting string directly back to the caller.
Tip
The @RestController and @RequestMapping annotations are Spring MVC annotations (they
are not specific to Spring Boot). See the MVC section in the Spring Reference Documentation
for more details.
The @EnableAutoConfiguration annotation
The second class-level annotation is @EnableAutoConfiguration. This annotation tells Spring
Boot to “guess” how you will want to configure Spring, based on the jar dependencies that you have
added. Since spring-boot-starter-web added Tomcat and Spring MVC, the auto-configuration
will assume that you are developing a web application and setup Spring accordingly.
Starters and Auto-Configuration
Auto-configuration is designed to work well with “Starters”, but the two concepts are not directly
tied. You are free to pick-and-choose jar dependencies outside of the starters and Spring Boot will
still do its best to auto-configure your application.
The “main” method
The final part of our application is the main method. This is just a standard method that follows
the Java convention for an application entry point. Our main method delegates to Spring Boot’s
SpringApplication class by calling run. SpringApplication will bootstrap our application,
starting Spring which will in turn start the auto-configured Tomcat web server. We need to pass
Example.class as an argument to the run method to tell SpringApplication which is the primary
Spring component. The args array is also passed through to expose any command-line arguments.
11.4 Running the example
At this point our application should work. Since we have used the spring-boot-starter-parent
POM we have a useful run goal that we can use to start the application. Type mvn spring-boot:run
from the root project directory to start the application:
$ mvn spring-boot:run
. ____ _ __ _ _
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 20
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v1.5.7.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)
If you open a web browser to localhost:8080 you should see the following output:
Hello World!
To gracefully exit the application hit ctrl-c.
11.5 Creating an executable jar
Let’s finish our example by creating a completely self-contained executable jar file that we could run in
production. Executable jars (sometimes called “fat jars”) are archives containing your compiled classes
along with all of the jar dependencies that your code needs to run.
Executable jars and Java
Java does not provide any standard way to load nested jar files (i.e. jar files that are themselves
contained within a jar). This can be problematic if you are looking to distribute a self-contained
application.
To solve this problem, many developers use “uber” jars. An uber jar simply packages all classes,
from all jars, into a single archive. The problem with this approach is that it becomes hard to see
which libraries you are actually using 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 allows you to actually nest jars directly.
To create an executable jar we need to add the spring-boot-maven-plugin to our pom.xml. Insert
the following lines just below the dependencies section:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
Note
The spring-boot-starter-parent POM includes <executions> configuration to bind the
repackage goal. If you are not using the parent POM you will need to declare this configuration
yourself. See the plugin documentation for details.
Save your pom.xml and run mvn package from the command line:
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 21
$ mvn package
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myproject 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] .... ..
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:1.5.7.RELEASE:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
If you look in the target directory you should see myproject-0.0.1-SNAPSHOT.jar. The file
should be around 10 MB in size. If you want to peek inside, you can use jar tvf:
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar
You should also see a much smaller file named myproject-0.0.1-SNAPSHOT.jar.original in
the target directory. This is the original jar file that Maven created before it was repackaged by Spring
Boot.
To run that application, use the java -jar command:
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v1.5.7.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)
As before, to gracefully exit the application hit ctrl-c.
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 22
12. What to read next
Hopefully this section has provided you with some of the Spring Boot basics, and got you on your way
to writing your own applications. If you’re a task-oriented type of developer you might want to jump over
to spring.io and check out some of the getting started guides that solve specific “How do I do that with
Spring” problems; we also have Spring Boot-specific How-to reference documentation.
The Spring Boot repository has also a bunch of samples you can run. The samples are independent of
the rest of the code (that is you don’t need to build the rest to run or use the samples).
Otherwise, the next logical step is to read Part III, “Using Spring Boot”. If you’re really impatient, you
could also jump ahead and read about Spring Boot features.
Part III. Using Spring Boot
This section goes into more detail about how you should use Spring Boot. It covers topics such as build
systems, auto-configuration and how to run your applications. We also cover some Spring Boot best
practices. Although there is nothing particularly special about Spring Boot (it is just another library that
you can consume), there are a few recommendations that, when followed, will make your development
process just a little easier.
If you’re just starting out with Spring Boot, you should probably read the Getting Started guide before
diving into this section.
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 24
13. Build systems
It is strongly recommended that you choose a build system that supports dependency management,
and one that can consume artifacts published to the “Maven Central” repository. We would recommend
that you choose Maven or Gradle. It is possible to get Spring Boot to work with other build systems (Ant
for example), but they will not be particularly well supported.
13.1 Dependency management
Each release of Spring Boot provides a curated list of dependencies it supports. In practice, you do not
need to provide a version for any of these dependencies in your build configuration as Spring Boot is
managing that for you. When you upgrade Spring Boot itself, these dependencies will be upgraded as
well in a consistent way.
Note
You can still specify a version and override Spring Boot’s recommendations if you feel that’s
necessary.
The curated list contains all the spring modules that you can use with Spring Boot as well as a
refined list of third party libraries. The list is available as a standard Bills of Materials (spring-boot-
dependencies) and additional dedicated support for Maven and Gradle are available as well.
Warning
Each release of Spring Boot is associated with a base version of the Spring Framework so we
highly recommend you to not specify its version on your own.
13.2 Maven
Maven users can inherit from the spring-boot-starter-parent project to obtain sensible defaults.
The parent project provides the following features:
• Java 1.6 as the default compiler level.
• UTF-8 source encoding.
• A Dependency Management section, allowing you to omit <version> tags for common
dependencies, inherited from the spring-boot-dependencies POM.
• Sensible resource filtering.
• Sensible plugin configuration (exec plugin, surefire, Git commit ID, shade).
• Sensible resource filtering for application.properties and application.yml including
profile-specific files (e.g. application-foo.properties and application-foo.yml)
On the last point: since the default config files accept Spring style placeholders (${…}) the Maven
filtering is changed to use @..@ placeholders (you can override that with a Maven property
resource.delimiter).
Inheriting the starter parent
To configure your project to inherit from the spring-boot-starter-parent simply set the parent:
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 25
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.7.RELEASE</version>
</parent>
Note
You should only need to specify the Spring Boot version number on this dependency. If you import
additional starters, you can safely omit the version number.
With that setup, you can also override individual dependencies by overriding a property in your own
project. For instance, to upgrade to another Spring Data release train you’d add the following to your
pom.xml.
<properties>
<spring-data-releasetrain.version>Fowler-SR2</spring-data-releasetrain.version>
</properties>
Tip
Check the spring-boot-dependencies pom for a list of supported properties.
Using Spring Boot without the parent POM
Not everyone likes inheriting from the spring-boot-starter-parent POM. You may have your
own corporate standard parent that you need to use, or you may just prefer to explicitly declare all your
Maven configuration.
If you don’t want to use the spring-boot-starter-parent, you can still keep the benefit of the
dependency management (but not the plugin management) by using a scope=import dependency:
<dependencyManagement>
<dependencies>
<dependency>
<!-- Import dependency management from Spring Boot -->
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>1.5.7.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
That setup does not allow you to override individual dependencies using a property as explained above.
To achieve the same result, you’d need to add an entry in the dependencyManagement of your project
before the spring-boot-dependencies entry. For instance, to upgrade to another Spring Data
release train you’d add the following to your pom.xml.
<dependencyManagement>
<dependencies>
<!-- Override Spring Data release train provided by Spring Boot -->
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-releasetrain</artifactId>
<version>Fowler-SR2</version>
<scope>import</scope>
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 26
<type>pom</type>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>1.5.7.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Note
In the example above, we specify a BOM but any dependency type can be overridden that way.
Changing the Java version
The spring-boot-starter-parent chooses fairly conservative Java compatibility. If you want to
follow our recommendation and use a later Java version you can add a java.version property:
<properties>
<java.version>1.8</java.version>
</properties>
Using the Spring Boot Maven plugin
Spring Boot includes a Maven plugin that can package the project as an executable jar. Add the plugin
to your <plugins> section if you want to use it:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
Note
If you use the Spring Boot starter parent pom, you only need to add the plugin, there is no need
for to configure it unless you want to change the settings defined in the parent.
13.3 Gradle
Gradle users can directly import ‘starters’ in their dependencies section. Unlike Maven, there is no
“super parent” to import to share some configuration.
repositories {
jcenter()
}
dependencies {
compile("org.springframework.boot:spring-boot-starter-web:1.5.7.RELEASE")
}
The spring-boot-gradle-plugin is also available and provides tasks to create executable jars
and run projects from source. It also provides dependency management that, among other capabilities,
allows you to omit the version number for any dependencies that are managed by Spring Boot:
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 27
plugins {
id 'org.springframework.boot' version '1.5.7.RELEASE'
id 'java'
}
repositories {
jcenter()
}
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
}
13.4 Ant
It is possible to build a Spring Boot project using Apache Ant+Ivy. The spring-boot-antlib “AntLib”
module is also available to help Ant create executable jars.
To declare dependencies a typical ivy.xml file will look something like this:
<ivy-module version="2.0">
<info organisation="org.springframework.boot" module="spring-boot-sample-ant" />
<configurations>
<conf name="compile" description="everything needed to compile this module" />
<conf name="runtime" extends="compile" description="everything needed to run this module" />
</configurations>
<dependencies>
<dependency org="org.springframework.boot" name="spring-boot-starter"
rev="${spring-boot.version}" conf="compile" />
</dependencies>
</ivy-module>
A typical build.xml will look like this:
<project
xmlns:ivy="antlib:org.apache.ivy.ant"
xmlns:spring-boot="antlib:org.springframework.boot.ant"
name="myapp" default="build">
<property name="spring-boot.version" value="1.3.0.BUILD-SNAPSHOT" />
<target name="resolve" description="--> retrieve dependencies with ivy">
<ivy:retrieve pattern="lib/[conf]/[artifact]-[type]-[revision].[ext]" />
</target>
<target name="classpaths" depends="resolve">
<path id="compile.classpath">
<fileset dir="lib/compile" includes="*.jar" />
</path>
</target>
<target name="init" depends="classpaths">
<mkdir dir="build/classes" />
</target>
<target name="compile" depends="init" description="compile">
<javac srcdir="src/main/java" destdir="build/classes" classpathref="compile.classpath" />
</target>
<target name="build" depends="compile">
<spring-boot:exejar destfile="build/myapp.jar" classes="build/classes">
<spring-boot:lib>
<fileset dir="lib/runtime" />
</spring-boot:lib>
</spring-boot:exejar>
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 28
</target>
</project>
Tip
See the Section 84.10, “Build an executable archive from Ant without using spring-boot-antlib”
“How-to” if you don’t want to use the spring-boot-antlib module.
13.5 Starters
Starters are a set of convenient dependency descriptors that you can include in your application. You
get a one-stop-shop for all the Spring and related technology that you need, without having to hunt
through sample code and copy paste loads of dependency descriptors. For example, if you want to get
started using Spring and JPA for database access, just include the spring-boot-starter-data-
jpa dependency in your project, and you are good to go.
The starters contain a lot of the dependencies that you need to get a project up and running quickly and
with a consistent, supported set of managed transitive dependencies.
What’s in a name
All official starters follow a similar naming pattern; spring-boot-starter-*, where * is a
particular type of application. This naming structure is intended to help when you need to find
a starter. The Maven integration in many IDEs allow you to search dependencies by name. For
example, with the appropriate Eclipse or STS plugin installed, you can simply hit ctrl-space in
the POM editor and type “spring-boot-starter” for a complete list.
As explained in the Creating your own starter section, third party starters should not start with
spring-boot as it is reserved for official Spring Boot artifacts. A third-party starter for acme will
be typically named acme-spring-boot-starter.
The following application starters are provided by Spring Boot under the
org.springframework.boot group:
Table 13.1. Spring Boot application starters
Name Description Pom
spring-boot-starter Core starter, including auto-
configuration support, logging
and YAML
Pom
spring-boot-starter-
activemq
Starter for JMS messaging
using Apache ActiveMQ
Pom
spring-boot-starter-
amqp
Starter for using Spring AMQP
and Rabbit MQ
Pom
spring-boot-starter-aop Starter for aspect-oriented
programming with Spring AOP
and AspectJ
Pom
spring-boot-starter-
artemis
Starter for JMS messaging
using Apache Artemis
Pom
Spring Boot Reference Guide
1.5.7.RELEASE Spring Boot 29
Name Description Pom
spring-boot-starter-
batch
Starter for using Spring Batch Pom
spring-boot-starter-
cache
Starter for using Spring
Framework’s caching support
Pom
spring-boot-starter-
cloud-connectors
Starter for using Spring Cloud
Connectors which simplifies
connecting to services in cloud
platforms like Cloud Foundry
and Heroku
Pom
spring-boot-starter-
data-cassandra
Starter for using Cassandra
distributed database and Spring
Data Cassandra
Pom
spring-boot-starter-
data-couchbase
Starter for using Couchbase
document-oriented database
and Spring Data Couchbase
Pom
spring-boot-starter-
data-elasticsearch
Starter for using Elasticsearch
search and analytics engine
and Spring Data Elasticsearch
Pom
spring-boot-starter-
data-gemfire
Starter for using GemFire
distributed data store and
Spring Data GemFire
Pom
spring-boot-starter-
data-jpa
Starter for using Spring Data
JPA with Hibernate
Pom
spring-boot-starter-
data-ldap
Starter for using Spring Data
LDAP
Pom
spring-boot-starter-
data-mongodb
Starter for using MongoDB
document-oriented database
and Spring Data MongoDB
Pom
spring-boot-starter-
data-neo4j
Starter for using Neo4j graph
database and Spring Data
Neo4j
Pom
spring-boot-starter-
data-redis
Starter for using Redis key-
value data store with Spring
Data Redis and the Jedis client
Pom
spring-boot-starter-
data-rest
Starter for exposing Spring
Data repositories over REST