Spring Boot Reference Guide

Authors

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

1.0.1.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. 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. MongoDB
27.1.1. Connecting to a MongoDB database
27.1.2. MongoTemplate
27.1.3. Spring Data MongoDB repositories
28. Testing
28.1. Test scope dependencies
28.2. Testing Spring applications
28.3. Testing Spring Boot applications
28.4. Test utilities
28.4.1. ConfigFileApplicationContextInitializer
28.4.2. EnvironmentTestUtils
28.4.3. OutputCapture
28.4.4. TestRestTemplate
29. Developing auto-configuration and using conditions
29.1. Understanding auto-configured beans
29.2. Locating auto-configuration candidates
29.3. Condition annotations
29.3.1. Class conditions
29.3.2. Bean conditions
29.3.3. Resource conditions
29.3.4. Web Application Conditions
29.3.5. SpEL expression conditions
30. What to read next
V. Production-ready features
31. Enabling production-ready features.
32. Endpoints
32.1. Customizing endpoints
32.2. Custom health information
32.3. Custom application info information
32.3.1. Git commit information
33. Monitoring and management over HTTP
33.1. Exposing sensitive endpoints
33.2. Customizing the management server context path
33.3. Customizing the management server port
33.4. Customizing the management server address
33.5. Disabling HTTP endpoints
34. Monitoring and management over JMX
34.1. Customizing MBean names
34.2. Disabling JMX endpoints
34.3. Using Jolokia for JMX over HTTP
34.3.1. Customizing Jolokia
34.3.2. Disabling Jolokia
35. Monitoring and management using a remote shell
35.1. Connecting to the remote shell
35.1.1. Remote shell credentials
35.2. Extending the remote shell
35.2.1. Remote shell commands
35.2.2. Remote shell plugins
36. Metrics
36.1. Recording your own metrics
36.2. Metric repositories
36.3. Coda Hale Metrics
36.4. Message channel integration
37. Auditing
38. Tracing
38.1. Custom tracing
39. Error Handling
40. What to read next
VI. Deploying to the cloud
41. Cloud Foundry
41.1. Binding to services
42. Heroku
43. CloudBees
44. What to read next
VII. Spring Boot CLI
45. Installing the CLI
46. Using the CLI
46.1. Running applications using the CLI
46.1.1. Deduced “grab” dependencies
46.1.2. Default import statements
46.1.3. Automatic main method
46.2. Testing your code
46.3. Applications with multiple source files
46.4. Packaging your application
46.5. Using the embedded shell
47. Developing application with the Groovy beans DSL
48. What to read next
VIII. Build tool plugins
49. Spring Boot Maven plugin
49.1. Including the plugin
49.2. Packaging executable jar and war files
49.3. Repackage configuration
49.3.1. Required parameters
49.3.2. Optional parameters
49.4. Running applications
49.5. Run configuration
49.6. Required parameters
49.7. Optional parameters
50. Spring Boot Gradle plugin
50.1. Including the plugin
50.2. Declaring dependencies without versions
50.3. Packaging executable jar and war files
50.4. Running a project in-place
50.5. Repackage configuration
50.6. Repackage with custom Gradle configuration
50.6.1. Configuration options
50.7. Understanding how the Gradle plugin works
51. Supporting other build systems
51.1. Repackaging archives
51.2. Nested libraries
51.3. Finding a main class
51.4. Example repackage implementation
52. What to read next
IX. “How-to” guides
53. Spring Boot application
53.1. Troubleshoot auto-configuration
53.2. Customize the Environment or ApplicationContext before it starts
53.3. Build an ApplicationContext hierarchy (adding a parent or root context)
53.4. Create a non-web application
54. Properties & configuration
54.1. Externalize the configuration of SpringApplication
54.2. Change the location of external properties of an application
54.3. Use “short” command line arguments
54.4. Use YAML for external properties
54.5. Set the active Spring profiles
54.6. Change configuration depending on the environment
54.7. Discover built-in options for external properties
55. Embedded servlet containers
55.1. Add a Servlet, Filter or ServletContextListener to an application
55.2. Change the HTTP port
55.3. Use a random unassigned HTTP port
55.4. Discover the HTTP port at runtime
55.5. Configure Tomcat
55.6. Terminate SSL in Tomcat
55.7. Enable Multiple Connectors Tomcat
55.8. Use Jetty instead of Tomcat
55.9. Configure Jetty
55.10. Use Tomcat 8
55.11. Use Jetty 9
56. Spring MVC
56.1. Write a JSON REST service
56.2. Customize the Jackson ObjectMapper
56.3. Customize the @ResponseBody rendering
56.4. Switch off the Spring MVC DispatcherServlet
56.5. Switch off the Default MVC configuration
56.6. Customize ViewResolvers
57. Logging
57.1. Configure Logback for logging
57.2. Configure Log4j for logging
58. Data Access
58.1. Configure a DataSource
58.2. Use Spring Data repositories
58.3. Separate @Entity definitions from Spring configuration
58.4. Configure JPA properties
58.5. Use a custom EntityManagerFactory
58.6. Use a traditional persistence.xml
59. Database initialization
59.1. Initialize a database using JPA
59.2. Initialize a database using Hibernate
59.3. Initialize a database using Spring JDBC
59.4. Initialize a Spring Batch database
59.5. Use a higher level database migration tool
60. Batch applications
60.1. Execute Spring Batch jobs on startup
61. Actuator
61.1. Change the HTTP port or address of the actuator endpoints
61.2. Customize the “whitelabel” error page
62. Security
62.1. Switch off the Spring Boot security configuration
62.2. Change the AuthenticationManager and add user accounts
62.3. Enable HTTPS
63. Hot swapping
63.1. Reload static content
63.2. Reload Thymeleaf templates without restarting the container
63.3. Reload Java classes without restarting the container
64. Build
64.1. Build an executable archive with Ant
65. Traditional deployment
65.1. Create a deployable war file
65.2. Create a deployable war file for older servlet containers
65.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