Spring Boot Reference Guide


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


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. Using the @SpringBootApplication annotation
18. Running your application
18.1. Running from an IDE
18.2. Running as a packaged application
18.3. Using the Maven plugin
18.4. Using the Gradle plugin
18.5. Hot swapping
19. Packaging your application for production
20. What to read next
IV. Spring Boot features
21. SpringApplication
21.1. Customizing the Banner
21.2. Customizing SpringApplication
21.3. Fluent builder API
21.4. Application events and listeners
21.5. Web environment
21.6. Using the CommandLineRunner
21.7. Application exit
22. Externalized Configuration
22.1. Accessing command line properties
22.2. Application property files
22.3. Profile specific properties
22.4. Placeholders in properties
22.5. Using YAML instead of Properties
22.5.1. Loading YAML
22.5.2. Exposing YAML as properties in the Spring Environment
22.5.3. Multi-profile YAML documents
22.5.4. YAML shortcomings
22.6. Typesafe Configuration Properties
22.6.1. Relaxed binding
22.6.2. @ConfigurationProperties Validation
23. Profiles
23.1. Adding active profiles
23.2. Programmatically setting profiles
23.3. Profile specific configuration files
24. Logging
24.1. Log format
24.2. Console output
24.3. File output
24.4. Log Levels
24.5. Custom log configuration
25. Developing web applications
25.1. The ‘Spring Web MVC framework’
25.1.1. Spring MVC auto-configuration
25.1.2. HttpMessageConverters
25.1.3. MessageCodesResolver
25.1.4. Static Content
25.1.5. Template engines
25.1.6. Error Handling
Error Handling on WebSphere Application Server
25.2. JAX-RS and Jersey
25.3. Embedded servlet container support
25.3.1. Servlets and Filters
25.3.2. The EmbeddedWebApplicationContext
25.3.3. Customizing embedded servlet containers
Programmatic customization
Customizing ConfigurableEmbeddedServletContainer directly
25.3.4. JSP limitations
26. Security
27. Working with SQL databases
27.1. Configure a DataSource
27.1.1. Embedded Database Support
27.1.2. Connection to a production database
27.1.3. Connection to a JNDI DataSource
27.2. Using JdbcTemplate
27.3. JPA and ‘Spring Data’
27.3.1. Entity Classes
27.3.2. Spring Data JPA Repositories
27.3.3. Creating and dropping JPA databases
28. Working with NoSQL technologies
28.1. Redis
28.1.1. Connecting to Redis
28.2. MongoDB
28.2.1. Connecting to a MongoDB database
28.2.2. MongoTemplate
28.2.3. Spring Data MongoDB repositories
28.3. Gemfire
28.4. Solr
28.4.1. Connecting to Solr
28.4.2. Spring Data Solr repositories
28.5. Elasticsearch
28.5.1. Connecting to Elasticsearch
28.5.2. Spring Data Elasticsearch repositories
29. Messaging
29.1. JMS
29.1.1. HornetQ support
29.1.2. ActiveMQ support
29.1.3. Using a JNDI ConnectionFactory
29.1.4. Sending a message
29.1.5. Receiving a message
30. Distributed Transactions with JTA
30.1. Using an Atomikos transaction manager
30.2. Using a Bitronix transaction manager
30.3. Using a Java EE managed transaction manager
30.4. Mixing XA and non-XA JMS connections
30.5. Supporting an alternative embedded transaction manager
31. Spring Integration
32. Monitoring and management over JMX
33. Testing
33.1. Test scope dependencies
33.2. Testing Spring applications
33.3. Testing Spring Boot applications
33.3.1. Using Spock to test Spring Boot applications
33.4. Test utilities
33.4.1. ConfigFileApplicationContextInitializer
33.4.2. EnvironmentTestUtils
33.4.3. OutputCapture
33.4.4. TestRestTemplate
34. Developing auto-configuration and using conditions
34.1. Understanding auto-configured beans
34.2. Locating auto-configuration candidates
34.3. Condition annotations
34.3.1. Class conditions
34.3.2. Bean conditions
34.3.3. Resource conditions
34.3.4. Web Application Conditions
34.3.5. SpEL expression conditions
35. What to read next
V. Spring Boot Actuator: Production-ready features
36. Enabling production-ready features.
37. Endpoints
37.1. Customizing endpoints
37.2. Custom health information
37.3. Custom application info information
37.3.1. Automatically expand info properties at build time
Automatic property expansion using Maven
Automatic property expansion using Gradle
37.3.2. Git commit information
38. Monitoring and management over HTTP
38.1. Exposing sensitive endpoints
38.2. Customizing the management server context path
38.3. Customizing the management server port
38.4. Customizing the management server address
38.5. Disabling HTTP endpoints
39. Monitoring and management over JMX
39.1. Customizing MBean names
39.2. Disabling JMX endpoints
39.3. Using Jolokia for JMX over HTTP
39.3.1. Customizing Jolokia
39.3.2. Disabling Jolokia
40. Monitoring and management using a remote shell
40.1. Connecting to the remote shell
40.1.1. Remote shell credentials
40.2. Extending the remote shell
40.2.1. Remote shell commands
40.2.2. Remote shell plugins
41. Metrics
41.1. DataSource metrics
41.2. Recording your own metrics
41.3. Adding your own public metrics
41.4. Metric repositories
41.5. Coda Hale Metrics
41.6. Message channel integration
42. Auditing
43. Tracing
43.1. Custom tracing
44. Process monitoring
44.1. Extend configuration
44.2. Programmatically
45. What to read next
VI. Deploying to the cloud
46. Cloud Foundry
46.1. Binding to services
47. Heroku
48. CloudBees
49. Openshift
50. Google App Engine
51. What to read next
VII. Spring Boot CLI
52. Installing the CLI
53. Using the CLI
53.1. Running applications using the CLI
53.2. Adding dependencies to the CLI
53.2.1. Deduced “grab” dependencies
53.2.2. Deduced “grab” coordinates
Custom “grab” metadata
53.2.3. Default import statements
53.2.4. Automatic main method
53.3. Testing your code
53.4. Applications with multiple source files
53.5. Packaging your application
53.6. Using the embedded shell
54. Developing application with the Groovy beans DSL
55. What to read next
VIII. Build tool plugins
56. Spring Boot Maven plugin
56.1. Including the plugin
56.2. Packaging executable jar and war files
57. Spring Boot Gradle plugin
57.1. Including the plugin
57.2. Declaring dependencies without versions
57.2.1. Custom version management
57.3. Default exclude rules
57.4. Packaging executable jar and war files
57.5. Running a project in-place
57.6. Spring Boot plugin configuration
57.7. Repackage configuration
57.8. Repackage with custom Gradle configuration
57.8.1. Configuration options
57.9. Understanding how the Gradle plugin works
57.10. Publishing artifacts to a Maven repository using Gradle
57.10.1. Configuring Gradle to produce a pom that inherits dependency management
57.10.2. Configuring Gradle to produce a pom that imports dependency management
58. Supporting other build systems
58.1. Repackaging archives
58.2. Nested libraries
58.3. Finding a main class
58.4. Example repackage implementation
59. What to read next
IX. ‘How-to’ guides
60. Spring Boot application
60.1. Troubleshoot auto-configuration
60.2. Customize the Environment or ApplicationContext before it starts
60.3. Build an ApplicationContext hierarchy (adding a parent or root context)
60.4. Create a non-web application
61. Properties & configuration
61.1. Externalize the configuration of SpringApplication
61.2. Change the location of external properties of an application
61.3. Use ‘short’ command line arguments
61.4. Use YAML for external properties
61.5. Set the active Spring profiles
61.6. Change configuration depending on the environment
61.7. Discover built-in options for external properties
62. Embedded servlet containers
62.1. Add a Servlet, Filter or ServletContextListener to an application
62.2. Change the HTTP port
62.3. Use a random unassigned HTTP port
62.4. Discover the HTTP port at runtime
62.5. Configure SSL
62.6. Configure Tomcat
62.7. Enable Multiple Connectors with Tomcat
62.8. Use Tomcat behind a front-end proxy server
62.9. Use Jetty instead of Tomcat
62.10. Configure Jetty
62.11. Use Tomcat 8
62.12. Use Jetty 9
62.13. Create WebSocket endpoints using @ServerEndpoint
63. Spring MVC
63.1. Write a JSON REST service
63.2. Write an XML REST service
63.3. Customize the Jackson ObjectMapper
63.4. Customize the @ResponseBody rendering
63.5. Handling Multipart File Uploads
63.6. Switch off the Spring MVC DispatcherServlet
63.7. Switch off the Default MVC configuration
63.8. Customize ViewResolvers
64. Logging
64.1. Configure Logback for logging
64.2. Configure Log4j for logging
65. Data Access
65.1. Configure a DataSource
65.2. Configure Two DataSources
65.3. Use Spring Data repositories
65.4. Separate @Entity definitions from Spring configuration
65.5. Configure JPA properties
65.6. Use a custom EntityManagerFactory
65.7. Use Two EntityManagers
65.8. Use a traditional persistence.xml
65.9. Use Spring Data JPA and Mongo repositories
66. Database initialization
66.1. Initialize a database using JPA
66.2. Initialize a database using Hibernate
66.3. Initialize a database using Spring JDBC
66.4. Initialize a Spring Batch database
66.5. Use a higher level database migration tool
66.5.1. Execute Flyway database migrations on startup
66.5.2. Execute Liquibase database migrations on startup
67. Batch applications
67.1. Execute Spring Batch jobs on startup
68. Actuator
68.1. Change the HTTP port or address of the actuator endpoints
68.2. Customize the ‘whitelabel’ error page
69. Security
69.1. Switch off the Spring Boot security configuration
69.2. Change the AuthenticationManager and add user accounts
69.3. Enable HTTPS when running behind a proxy server
70. Hot swapping
70.1. Reload static content
70.2. Reload Thymeleaf templates without restarting the container
70.3. Reload FreeMarker templates without restarting the container
70.4. Reload Groovy templates without restarting the container
70.5. Reload Velocity templates without restarting the container
70.6. Reload Java classes without restarting the container
70.6.1. Configuring Spring Loaded for use with Maven
70.6.2. Configuring Spring Loaded for use with Gradle and IntelliJ
71. Build
71.1. Customize dependency versions with Maven
71.2. Create an executable JAR with Maven
71.3. Create an additional executable JAR
71.4. Extract specific libraries when an executable jar runs
71.5. Create a non-executable JAR with exclusions
71.6. Remote debug a Spring Boot application started with Maven
71.7. Remote debug a Spring Boot application started with Gradle
71.8. Build an executable archive with Ant
72. Traditional deployment
72.1. Create a deployable war file
72.2. Create a deployable war file for older servlet containers
72.3. Convert an existing application to Spring Boot
72.4. Deploying a WAR in an Old (Servlet 2.5) Container
X. Appendices
A. Common application properties
B. Configuration meta-data
B.1. Meta-data format
B.1.1. Group Attributes
B.1.2. Property Attributes
B.1.3. Repeated meta-data items
B.2. Generating your own meta-data using the annotation processor
B.2.1. Nested properties
B.2.2. Adding additional meta-data
C. Auto-configuration classes
C.1. From the “spring-boot-autoconfigure” module
C.2. From the “spring-boot-actuator” module
D. The executable jar format
D.1. Nested JARs
D.1.1. The executable jar file structure
D.1.2. The executable war file structure
D.2. Spring Boot’s “JarFile” class
D.2.1. Compatibility with the standard Java “JarFile”
D.3. Launching executable jars
D.3.1. Launcher manifest
D.3.2. Exploded archives
D.4. PropertiesLauncher Features
D.5. Executable jar restrictions
D.5.1. Zip entry compression
D.5.2. System ClassLoader
D.6. Alternative single jar solutions
E. Dependency versions