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 ConfigurableEmbeddedServletContainer 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.1.3. Connection to a JNDI DataSource
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 a JNDI ConnectionFactory
28.1.4. Sending a message
28.1.5. Receiving a message
29. Distributed Transactions with JTA
29.1. Using an Atomikos transaction manager
29.2. Using a Bitronix transaction manager
29.3. Using a Java EE managed transaction manager
29.4. Mixing XA and non-XA JMS connections
29.5. Supporting an alternative embedded transaction manager
30. Spring Integration
31. Monitoring and management over JMX
32. Testing
32.1. Test scope dependencies
32.2. Testing Spring applications
32.3. Testing Spring Boot applications
32.3.1. Using Spock to test Spring Boot applications
32.4. Test utilities
32.4.1. ConfigFileApplicationContextInitializer
32.4.2. EnvironmentTestUtils
32.4.3. OutputCapture
32.4.4. TestRestTemplate
33. Developing auto-configuration and using conditions
33.1. Understanding auto-configured beans
33.2. Locating auto-configuration candidates
33.3. Condition annotations
33.3.1. Class conditions
33.3.2. Bean conditions
33.3.3. Resource conditions
33.3.4. Web Application Conditions
33.3.5. SpEL expression conditions
34. What to read next
V. Spring Boot Actuator: Production-ready features
35. Enabling production-ready features.
36. Endpoints
36.1. Customizing endpoints
36.2. Custom health information
36.3. Custom application info information
36.3.1. Git commit information
37. Monitoring and management over HTTP
37.1. Exposing sensitive endpoints
37.2. Customizing the management server context path
37.3. Customizing the management server port
37.4. Customizing the management server address
37.5. Disabling HTTP endpoints
38. Monitoring and management over JMX
38.1. Customizing MBean names
38.2. Disabling JMX endpoints
38.3. Using Jolokia for JMX over HTTP
38.3.1. Customizing Jolokia
38.3.2. Disabling Jolokia
39. Monitoring and management using a remote shell
39.1. Connecting to the remote shell
39.1.1. Remote shell credentials
39.2. Extending the remote shell
39.2.1. Remote shell commands
39.2.2. Remote shell plugins
40. Metrics
40.1. DataSource metrics
40.2. Recording your own metrics
40.3. Adding your own public metrics
40.4. Metric repositories
40.5. Coda Hale Metrics
40.6. Message channel integration
41. Auditing
42. Tracing
42.1. Custom tracing
43. Process monitoring
43.1. Extend configuration
43.2. Programmatically
44. What to read next
VI. Deploying to the cloud
45. Cloud Foundry
45.1. Binding to services
46. Heroku
47. CloudBees
48. Openshift
49. What to read next
VII. Spring Boot CLI
50. Installing the CLI
51. Using the CLI
51.1. Running applications using the CLI
51.1.1. Deduced “grab” dependencies
51.1.2. Deduced “grab” coordinates
Custom “grab” metadata
51.1.3. Default import statements
51.1.4. Automatic main method
51.2. Testing your code
51.3. Applications with multiple source files
51.4. Packaging your application
51.5. Using the embedded shell
52. Developing application with the Groovy beans DSL
53. What to read next
VIII. Build tool plugins
54. Spring Boot Maven plugin
54.1. Including the plugin
54.2. Packaging executable jar and war files
55. Spring Boot Gradle plugin
55.1. Including the plugin
55.2. Declaring dependencies without versions
55.2.1. Custom version management
55.3. Default exclude rules
55.4. Packaging executable jar and war files
55.5. Running a project in-place
55.6. Spring Boot plugin configuration
55.7. Repackage configuration
55.8. Repackage with custom Gradle configuration
55.8.1. Configuration options
55.9. Understanding how the Gradle plugin works
56. Supporting other build systems
56.1. Repackaging archives
56.2. Nested libraries
56.3. Finding a main class
56.4. Example repackage implementation
57. What to read next
IX. “How-to” guides
58. Spring Boot application
58.1. Troubleshoot auto-configuration
58.2. Customize the Environment or ApplicationContext before it starts
58.3. Build an ApplicationContext hierarchy (adding a parent or root context)
58.4. Create a non-web application
59. Properties & configuration
59.1. Externalize the configuration of SpringApplication
59.2. Change the location of external properties of an application
59.3. Use “short” command line arguments
59.4. Use YAML for external properties
59.5. Set the active Spring profiles
59.6. Change configuration depending on the environment
59.7. Discover built-in options for external properties
60. Embedded servlet containers
60.1. Add a Servlet, Filter or ServletContextListener to an application
60.2. Change the HTTP port
60.3. Use a random unassigned HTTP port
60.4. Discover the HTTP port at runtime
60.5. Configure SSL
60.6. Configure Tomcat
60.7. Enable Multiple Connectors Tomcat
60.8. Use Tomcat behind a front-end proxy server
60.9. Use Jetty instead of Tomcat
60.10. Configure Jetty
60.11. Use Tomcat 8
60.12. Use Jetty 9
61. Spring MVC
61.1. Write a JSON REST service
61.2. Write an XML REST service
61.3. Customize the Jackson ObjectMapper
61.4. Customize the @ResponseBody rendering
61.5. Handling Multipart File Uploads
61.6. Switch off the Spring MVC DispatcherServlet
61.7. Switch off the Default MVC configuration
61.8. Customize ViewResolvers
62. Logging
62.1. Configure Logback for logging
62.2. Configure Log4j for logging
63. Data Access
63.1. Configure a DataSource
63.2. Configure Two DataSources
63.3. Use Spring Data repositories
63.4. Separate @Entity definitions from Spring configuration
63.5. Configure JPA properties
63.6. Use a custom EntityManagerFactory
63.7. Use Two EntityManagers
63.8. Use a traditional persistence.xml
63.9. Use Spring Data JPA and Mongo repositories
64. Database initialization
64.1. Initialize a database using JPA
64.2. Initialize a database using Hibernate
64.3. Initialize a database using Spring JDBC
64.4. Initialize a Spring Batch database
64.5. Use a higher level database migration tool
64.5.1. Execute Flyway database migrations on startup
64.5.2. Execute Liquibase database migrations on startup
65. Batch applications
65.1. Execute Spring Batch jobs on startup
66. Actuator
66.1. Change the HTTP port or address of the actuator endpoints
66.2. Customize the “whitelabel” error page
67. Security
67.1. Switch off the Spring Boot security configuration
67.2. Change the AuthenticationManager and add user accounts
67.3. Enable HTTPS when running behind a proxy server
68. Hot swapping
68.1. Reload static content
68.2. Reload Thymeleaf templates without restarting the container
68.3. Reload FreeMarker templates without restarting the container
68.4. Reload Groovy templates without restarting the container
68.5. Reload Velocity templates without restarting the container
68.6. Reload Java classes without restarting the container
68.6.1. Configuring Spring Loaded for use with Gradle and IntelliJ
69. Build
69.1. Customize dependency versions with Maven
69.2. Create an executable JAR with Maven
69.3. Create an additional executable JAR
69.4. Extract specific libraries when an executable jar runs
69.5. Create a non-executable JAR with exclusions
69.6. Remote debug a Spring Boot application started with Maven
69.7. Remote debug a Spring Boot application started with Gradle
69.8. Build an executable archive with Ant
70. Traditional deployment
70.1. Create a deployable war file
70.2. Create a deployable war file for older servlet containers
70.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