Spring Boot Reference Guide


Phillip Webb , Dave Syer , Josh Long , Stéphane Nicoll , Rob Winch , Andy Wilkinson , Marcel Overdijk , Christian Dupuis


Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Table of Contents

I. Spring Boot Documentation
1. About the documentation
2. Getting help
3. First steps
4. Working with Spring Boot
5. Learning about Spring Boot features
6. Moving to production
7. Advanced topics
II. Getting started
8. Introducing Spring Boot
9. Installing Spring Boot
9.1. Installation instructions for the Java developer
9.1.1. Maven installation
9.1.2. Gradle installation
9.2. Installing the Spring Boot CLI
9.2.1. Manual installation
9.2.2. Installation with GVM
9.2.3. OSX Homebrew installation
9.2.4. Command-line completion
9.2.5. Quick start Spring CLI example
9.3. Upgrading from an earlier version of Spring Boot
10. Developing your first Spring Boot application
10.1. Creating the POM
10.2. Adding classpath dependencies
10.3. Writing the code
10.3.1. The @RestController and @RequestMapping annotations
10.3.2. The @EnableAutoConfiguration annotation
10.3.3. The “main” method
10.4. Running the example
10.5. Creating an executable jar
11. What to read next
III. Using Spring Boot
12. Build systems
12.1. Maven
12.1.1. Inheriting the starter parent
12.1.2. Using Spring Boot without the parent POM
12.1.3. Changing the Java version
12.1.4. Using the Spring Boot Maven plugin
12.2. Gradle
12.3. Ant
12.4. Starter POMs
13. Structuring your code
13.1. Using the “default” package
13.2. Locating the main application class
14. Configuration classes
14.1. Importing additional configuration classes
14.2. Importing XML configuration
15. Auto-configuration
15.1. Gradually replacing auto-configuration
15.2. Disabling specific auto-configuration
16. Spring Beans and dependency injection
17. Running your application
17.1. Running from an IDE
17.2. Running as a packaged application
17.3. Using the Maven plugin
17.4. Using the Gradle plugin
17.5. Hot swapping
18. Packaging your application for production
19. What to read next
IV. Spring Boot features
20. SpringApplication
20.1. Customizing the Banner
20.2. Customizing SpringApplication
20.3. Fluent builder API
20.4. Application events and listeners
20.5. Web environment
20.6. Using the CommandLineRunner
20.7. Application exit
21. Externalized Configuration
21.1. Accessing command line properties
21.2. Application property files
21.3. Profile specific properties
21.4. Placeholders in properties
21.5. Using YAML instead of Properties
21.5.1. Loading YAML
21.5.2. Exposing YAML as properties in the Spring Environment
21.5.3. Multi-profile YAML documents
21.5.4. YAML shortcomings
21.6. Typesafe Configuration Properties
21.6.1. Relaxed binding
21.6.2. @ConfigurationProperties Validation
22. Profiles
22.1. Adding active profiles
22.2. Programmatically setting profiles
22.3. Profile specific configuration files
23. Logging
23.1. Log format
23.2. Console output
23.3. File output
23.4. Log Levels
23.5. Custom log configuration
24. Developing web applications
24.1. The “Spring Web MVC framework”
24.1.1. Spring MVC auto-configuration
24.1.2. HttpMessageConverters
24.1.3. MessageCodesResolver
24.1.4. Static Content
24.1.5. Template engines
24.1.6. Error Handling
24.2. Embedded servlet container support
24.2.1. Servlets and Filters
24.2.2. The EmbeddedWebApplicationContext
24.2.3. Customizing embedded servlet containers
Programmatic customization
Customizing ConfigurableEmbeddedServletContainerFactory directly
24.2.4. JSP limitations
25. Security
26. Working with SQL databases
26.1. Configure a DataSource
26.1.1. Embedded Database Support
26.1.2. Connection to a production database
26.2. Using JdbcTemplate
26.3. JPA and “Spring Data”
26.3.1. Entity Classes
26.3.2. Spring Data JPA Repositories
26.3.3. Creating and dropping JPA databases
27. Working with NoSQL technologies
27.1. Redis
27.1.1. Connecting to Redis
27.2. MongoDB
27.2.1. Connecting to a MongoDB database
27.2.2. MongoTemplate
27.2.3. Spring Data MongoDB repositories
27.3. Gemfire
27.4. Solr
27.4.1. Connecting to Solr
27.4.2. Spring Data Solr repositories
27.5. Elasticsearch
27.5.1. Connecting to Elasticsearch
27.5.2. Spring Data Elasticsearch repositories
28. Messaging
28.1. JMS
28.1.1. HornetQ support
28.1.2. ActiveMQ support
28.1.3. Using JmsTemplate
29. Spring Integration
30. Monitoring and management over JMX
31. Testing
31.1. Test scope dependencies
31.2. Testing Spring applications
31.3. Testing Spring Boot applications
31.3.1. Using Spock to test Spring Boot applications
31.4. Test utilities
31.4.1. ConfigFileApplicationContextInitializer
31.4.2. EnvironmentTestUtils
31.4.3. OutputCapture
31.4.4. TestRestTemplate
32. Developing auto-configuration and using conditions
32.1. Understanding auto-configured beans
32.2. Locating auto-configuration candidates
32.3. Condition annotations
32.3.1. Class conditions
32.3.2. Bean conditions
32.3.3. Resource conditions
32.3.4. Web Application Conditions
32.3.5. SpEL expression conditions
33. What to read next
V. Spring Boot Actuator: Production-ready features
34. Enabling production-ready features.
35. Endpoints
35.1. Customizing endpoints
35.2. Custom health information
35.3. Custom application info information
35.3.1. Git commit information
36. Monitoring and management over HTTP
36.1. Exposing sensitive endpoints
36.2. Customizing the management server context path
36.3. Customizing the management server port
36.4. Customizing the management server address
36.5. Disabling HTTP endpoints
37. Monitoring and management over JMX
37.1. Customizing MBean names
37.2. Disabling JMX endpoints
37.3. Using Jolokia for JMX over HTTP
37.3.1. Customizing Jolokia
37.3.2. Disabling Jolokia
38. Monitoring and management using a remote shell
38.1. Connecting to the remote shell
38.1.1. Remote shell credentials
38.2. Extending the remote shell
38.2.1. Remote shell commands
38.2.2. Remote shell plugins
39. Metrics
39.1. Recording your own metrics
39.2. Metric repositories
39.3. Coda Hale Metrics
39.4. Message channel integration
40. Auditing
41. Tracing
41.1. Custom tracing
42. Process monitoring
42.1. Extend configuration
42.2. Programmatically
43. What to read next
VI. Deploying to the cloud
44. Cloud Foundry
44.1. Binding to services
45. Heroku
46. CloudBees
47. Openshift
48. What to read next
VII. Spring Boot CLI
49. Installing the CLI
50. Using the CLI
50.1. Running applications using the CLI
50.1.1. Deduced “grab” dependencies
50.1.2. Deduced “grab” coordinates
Custom “grab” metadata
50.1.3. Default import statements
50.1.4. Automatic main method
50.2. Testing your code
50.3. Applications with multiple source files
50.4. Packaging your application
50.5. Using the embedded shell
51. Developing application with the Groovy beans DSL
52. What to read next
VIII. Build tool plugins
53. Spring Boot Maven plugin
53.1. Including the plugin
53.2. Packaging executable jar and war files
54. Spring Boot Gradle plugin
54.1. Including the plugin
54.2. Declaring dependencies without versions
54.2.1. Custom version management
54.3. Default exclude rules
54.4. Packaging executable jar and war files
54.5. Running a project in-place
54.6. Spring Boot plugin configuration
54.7. Repackage configuration
54.8. Repackage with custom Gradle configuration
54.8.1. Configuration options
54.9. Understanding how the Gradle plugin works
55. Supporting other build systems
55.1. Repackaging archives
55.2. Nested libraries
55.3. Finding a main class
55.4. Example repackage implementation
56. What to read next
IX. “How-to” guides
57. Spring Boot application
57.1. Troubleshoot auto-configuration
57.2. Customize the Environment or ApplicationContext before it starts
57.3. Build an ApplicationContext hierarchy (adding a parent or root context)
57.4. Create a non-web application
58. Properties & configuration
58.1. Externalize the configuration of SpringApplication
58.2. Change the location of external properties of an application
58.3. Use “short” command line arguments
58.4. Use YAML for external properties
58.5. Set the active Spring profiles
58.6. Change configuration depending on the environment
58.7. Discover built-in options for external properties
59. Embedded servlet containers
59.1. Add a Servlet, Filter or ServletContextListener to an application
59.2. Change the HTTP port
59.3. Use a random unassigned HTTP port
59.4. Discover the HTTP port at runtime
59.5. Configure Tomcat
59.6. Terminate SSL in Tomcat
59.7. Enable Multiple Connectors Tomcat
59.8. Use Tomcat behind a front-end proxy server
59.9. Use Jetty instead of Tomcat
59.10. Configure Jetty
59.11. Use Tomcat 8
59.12. Use Jetty 9
60. Spring MVC
60.1. Write a JSON REST service
60.2. Write an XML REST service
60.3. Customize the Jackson ObjectMapper
60.4. Customize the @ResponseBody rendering
60.5. Handling Multipart File Uploads
60.6. Switch off the Spring MVC DispatcherServlet
60.7. Switch off the Default MVC configuration
60.8. Customize ViewResolvers
61. Logging
61.1. Configure Logback for logging
61.2. Configure Log4j for logging
62. Data Access
62.1. Configure a DataSource
62.2. Configure Two DataSources
62.3. Use Spring Data repositories
62.4. Separate @Entity definitions from Spring configuration
62.5. Configure JPA properties
62.6. Use a custom EntityManagerFactory
62.7. Use Two EntityManagers
62.8. Use a traditional persistence.xml
62.9. Use Spring Data JPA and Mongo repositories
63. Database initialization
63.1. Initialize a database using JPA
63.2. Initialize a database using Hibernate
63.3. Initialize a database using Spring JDBC
63.4. Initialize a Spring Batch database
63.5. Use a higher level database migration tool
63.5.1. Execute Flyway database migrations on startup
63.5.2. Execute Liquibase database migrations on startup
64. Batch applications
64.1. Execute Spring Batch jobs on startup
65. Actuator
65.1. Change the HTTP port or address of the actuator endpoints
65.2. Customize the “whitelabel” error page
66. Security
66.1. Switch off the Spring Boot security configuration
66.2. Change the AuthenticationManager and add user accounts
66.3. Enable HTTPS when running behind a proxy server
67. Hot swapping
67.1. Reload static content
67.2. Reload Thymeleaf templates without restarting the container
67.3. Reload FreeMarker templates without restarting the container
67.4. Reload Groovy templates without restarting the container
67.5. Reload Velocity templates without restarting the container
67.6. Reload Java classes without restarting the container
67.6.1. Configuring Spring Loaded for use with Gradle and IntelliJ
68. Build
68.1. Customize dependency versions with Maven
68.2. Create an executable JAR with Maven
68.3. Create an additional executable JAR
68.4. Extract specific libraries when an executable jar runs
68.5. Create a non-executable JAR with exclusions
68.6. Remote debug a Spring Boot application started with Maven
68.7. Remote debug a Spring Boot application started with Gradle
68.8. Build an executable archive with Ant
69. Traditional deployment
69.1. Create a deployable war file
69.2. Create a deployable war file for older servlet containers
69.3. Convert an existing application to Spring Boot
X. Appendices
A. Common application properties
B. Auto-configuration classes
B.1. From the “spring-boot-autoconfigure” module
B.2. From the “spring-boot-actuator” module
C. The executable jar format
C.1. Nested JARs
C.1.1. The executable jar file structure
C.1.2. The executable war file structure
C.2. Spring Boot’s “JarFile” class
C.2.1. Compatibility with the standard Java “JarFile”
C.3. Launching executable jars
C.3.1. Launcher manifest
C.3.2. Exploded archives
C.4. PropertiesLauncher Features
C.5. Executable jar restrictions
C.5.1. Zip entry compression
C.5.2. System ClassLoader
C.6. Alternative single jar solutions
D. Dependency versions