Spring Boot Reference Guide

Authors

Phillip Webb , Dave Syer , Josh Long , Stéphane Nicoll , Rob Winch

1.0.0.RELEASE

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
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 @Controller, @RequestMapping and @ResponseBody 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 your own 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 SpringApplication
20.2. Fluent builder API
20.3. Application events and listeners
20.4. Web environment
20.5. Using the CommandLineRunner
20.6. 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. 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. Static Content
24.1.4. Template engines
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. Working with SQL databases
25.1. Configure a DataSource
25.1.1. Embedded Database Support
25.1.2. Connection to a production database
25.2. Using JdbcTemplate
25.3. JPA and “Spring Data”
25.3.1. Entity Classes
25.3.2. Spring Data JPA Repositories
25.3.3. Creating and dropping JPA databases
26. Working with NoSQL technologies
26.1. MongoDB
26.1.1. Connecting to a MongoDB database
26.1.2. MongoTemplate
26.1.3. Spring Data MongoDB repositories
27. Testing
27.1. Test scope dependencies
27.2. Testing Spring applications
27.3. Testing Spring Boot applications
27.4. Test utilities
27.4.1. ConfigFileApplicationContextInitializer
27.4.2. EnvironmentTestUtils
27.4.3. OutputCapture
27.4.4. TestRestTemplate
28. Developing auto-configuration and using conditions
28.1. Understanding auto-configured beans
28.2. Locating auto-configuration candidates
28.3. Condition annotations
28.3.1. Class conditions
28.3.2. Bean conditions
28.3.3. Resource conditions
28.3.4. Web Application Conditions
28.3.5. SpEL expression conditions
29. What to read next
V. Production-ready features
30. Enabling production-ready features.
31. Endpoints
31.1. Customizing endpoints
31.2. Custom health information
31.3. Custom application info information
31.3.1. Git commit information
32. Monitoring and management over HTTP
32.1. Exposing sensitive endpoints
32.2. Customizing the management server context path
32.3. Customizing the management server port
32.4. Customizing the management server address
32.5. Disabling HTTP endpoints
33. Monitoring and management over JMX
33.1. Customizing MBean names
33.2. Disabling JMX endpoints
33.3. Using Jolokia for JMX over HTTP
33.3.1. Customizing Jolokia
33.3.2. Disabling Jolokia
34. Monitoring and management using a remote shell
34.1. Connecting to the remote shell
34.1.1. Remote shell credentials
34.2. Extending the remote shell
34.2.1. Remote shell commands
34.2.2. Remote shell plugins
35. Metrics
35.1. Recording your own metrics
35.2. Metric repositories
35.3. Coda Hale Metrics
35.4. Message channel integration
36. Auditing
37. Tracing
37.1. Custom tracing
38. Error Handling
39. What to read next
VI. Deploying to the cloud
40. Cloud Foundry
40.1. Binding to services
41. Heroku
42. CloudBees
43. What to read next
VII. Spring Boot CLI
44. Installing the CLI
45. Using the CLI
45.1. Running applications using the CLI
45.1.1. Deduced “grab” dependencies
45.1.2. Default import statements
45.1.3. Automatic main method
45.2. Testing your code
45.3. Applications with multiple source files
45.4. Packaging your application
45.5. Using the embedded shell
46. Developing application with the Groovy beans DSL
47. What to read next
VIII. Build tool plugins
48. Spring Boot Maven plugin
48.1. Including the plugin
48.2. Packaging executable jar and war files
48.3. Repackage configuration
48.3.1. Required parameters
48.3.2. Optional parameters
48.4. Running applications
48.5. Run configuration
48.6. Required parameters
48.7. Optional parameters
49. Spring Boot Gradle plugin
49.1. Including the plugin
49.2. Declaring dependencies without versions
49.3. Packaging executable jar and war files
49.4. Running a project in-place
49.5. Repackage configuration
49.6. Repackage with custom Gradle configuration
49.6.1. Configuration options
49.7. Understanding how the Gradle plugin works
50. Supporting other build systems
50.1. Repackaging archives
50.2. Nested libraries
50.3. Finding a main class
50.4. Example repackage implementation
51. What to read next
IX. “How-to” guides
52. Spring Boot application
52.1. Troubleshoot auto-configuration
52.2. Customize the Environment or ApplicationContext before it starts
52.3. Build an ApplicationContext hierarchy (adding a parent or root context)
52.4. Create a non-web application
53. Properties & configuration
53.1. Externalize the configuration of SpringApplication
53.2. Change the location of external properties of an application
53.3. Use “short” command line arguments
53.4. Use YAML for external properties
53.5. Set the active Spring profiles
53.6. Change configuration depending on the environment
53.7. Discover built-in options for external properties
54. Embedded servlet containers
54.1. Add a Servlet, Filter or ServletContextListener to an application
54.2. Change the HTTP port
54.3. Use a random unassigned HTTP port
54.4. Discover the HTTP port at runtime
54.5. Configure Tomcat
54.6. Terminate SSL in Tomcat
54.7. Enable Multiple Connectors Tomcat
54.8. Use Jetty instead of Tomcat
54.9. Configure Jetty
54.10. Use Tomcat 8
54.11. Use Jetty 9
55. Spring MVC
55.1. Write a JSON REST service
55.2. Customize the Jackson ObjectMapper
55.3. Customize the @ResponseBody rendering
55.4. Switch off the Spring MVC DispatcherServlet
55.5. Switch off the Default MVC configuration
55.6. Customize ViewResolvers
56. Logging
56.1. Configure Logback for logging
56.2. Configure Log4j for logging
57. Data Access
57.1. Configure a DataSource
57.2. Use Spring Data repositories
57.3. Separate @Entity definitions from Spring configuration
57.4. Configure JPA properties
57.5. Use a traditional persistence.xml
58. Database initialization
58.1. Initialize a database using JPA
58.2. Initialize a database using Hibernate
58.3. Initialize a database using Spring JDBC
58.4. Initialize a Spring Batch database
58.5. Use a higher level database migration tool
59. Batch applications
59.1. Execute Spring Batch jobs on startup
60. Actuator
60.1. Change the HTTP port or address of the actuator endpoints
60.2. Customize the “whitelabel” error page
61. Security
61.1. Secure an application
61.2. Switch off the Spring Boot security configuration
61.3. Change the AuthenticationManager and add user accounts
61.4. Enable HTTPS
62. Hot swapping
62.1. Reload static content
62.2. Reload Thymeleaf templates without restarting the container
62.3. Reload Java classes without restarting the container
63. Build
63.1. Build an executable archive with Ant
64. Traditional deployment
64.1. Create a deployable war file
64.2. Create a deployable war file for older servlet containers
64.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