Spring Boot Reference Guide
   Next

Spring Boot Reference Guide

Authors

Phillip Webb, Dave Syer, Josh Long, Stéphane Nicoll, Rob Winch, Andy Wilkinson, Marcel Overdijk, Christian Dupuis, Sébastien Deleuze, Michael Simons, Vedran Pavić, Jay Bryant, Madhura Bhave

2.0.9.RELEASE

Copyright © 2012-2018

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. System Requirements
9.1. Servlet Containers
10. Installing Spring Boot
10.1. Installation Instructions for the Java Developer
10.1.1. Maven Installation
10.1.2. Gradle Installation
10.2. Installing the Spring Boot CLI
10.2.1. Manual Installation
10.2.2. Installation with SDKMAN!
10.2.3. OSX Homebrew Installation
10.2.4. MacPorts Installation
10.2.5. Command-line Completion
10.2.6. Windows Scoop Installation
10.2.7. Quick-start Spring CLI Example
10.3. Upgrading from an Earlier Version of Spring Boot
11. Developing Your First Spring Boot Application
11.1. Creating the POM
11.2. Adding Classpath Dependencies
11.3. Writing the Code
11.3.1. The @RestController and @RequestMapping Annotations
11.3.2. The @EnableAutoConfiguration Annotation
11.3.3. The “main” Method
11.4. Running the Example
11.5. Creating an Executable Jar
12. What to Read Next
III. Using Spring Boot
13. Build Systems
13.1. Dependency Management
13.2. Maven
13.2.1. Inheriting the Starter Parent
13.2.2. Using Spring Boot without the Parent POM
13.2.3. Using the Spring Boot Maven Plugin
13.3. Gradle
13.4. Ant
13.5. Starters
14. Structuring Your Code
14.1. Using the “default” Package
14.2. Locating the Main Application Class
15. Configuration Classes
15.1. Importing Additional Configuration Classes
15.2. Importing XML Configuration
16. Auto-configuration
16.1. Gradually Replacing Auto-configuration
16.2. Disabling Specific Auto-configuration Classes
17. Spring Beans and Dependency Injection
18. Using the @SpringBootApplication Annotation
19. Running Your Application
19.1. Running from an IDE
19.2. Running as a Packaged Application
19.3. Using the Maven Plugin
19.4. Using the Gradle Plugin
19.5. Hot Swapping
20. Developer Tools
20.1. Property Defaults
20.2. Automatic Restart
20.2.1. Logging changes in condition evaluation
20.2.2. Excluding Resources
20.2.3. Watching Additional Paths
20.2.4. Disabling Restart
20.2.5. Using a Trigger File
20.2.6. Customizing the Restart Classloader
20.2.7. Known Limitations
20.3. LiveReload
20.4. Global Settings
20.5. Remote Applications
20.5.1. Running the Remote Client Application
20.5.2. Remote Update
21. Packaging Your Application for Production
22. What to Read Next
IV. Spring Boot features
23. SpringApplication
23.1. Startup Failure
23.2. Customizing the Banner
23.3. Customizing SpringApplication
23.4. Fluent Builder API
23.5. Application Events and Listeners
23.6. Web Environment
23.7. Accessing Application Arguments
23.8. Using the ApplicationRunner or CommandLineRunner
23.9. Application Exit
23.10. Admin Features
24. Externalized Configuration
24.1. Configuring Random Values
24.2. Accessing Command Line Properties
24.3. Application Property Files
24.4. Profile-specific Properties
24.5. Placeholders in Properties
24.6. Encrypting Properties
24.7. Using YAML Instead of Properties
24.7.1. Loading YAML
24.7.2. Exposing YAML as Properties in the Spring Environment
24.7.3. Multi-profile YAML Documents
24.7.4. YAML Shortcomings
24.8. Type-safe Configuration Properties
24.8.1. Third-party Configuration
24.8.2. Relaxed Binding
24.8.3. Merging Complex Types
24.8.4. Properties Conversion
Converting durations
24.8.5. @ConfigurationProperties Validation
24.8.6. @ConfigurationProperties vs. @Value
25. Profiles
25.1. Adding Active Profiles
25.2. Programmatically Setting Profiles
25.3. Profile-specific Configuration Files
26. Logging
26.1. Log Format
26.2. Console Output
26.2.1. Color-coded Output
26.3. File Output
26.4. Log Levels
26.5. Custom Log Configuration
26.6. Logback Extensions
26.6.1. Profile-specific Configuration
26.6.2. Environment Properties
27. JSON
27.1. Jackson
27.2. Gson
27.3. JSON-B
28. Developing Web Applications
28.1. The “Spring Web MVC Framework”
28.1.1. Spring MVC Auto-configuration
28.1.2. HttpMessageConverters
28.1.3. Custom JSON Serializers and Deserializers
28.1.4. MessageCodesResolver
28.1.5. Static Content
28.1.6. Welcome Page
28.1.7. Custom Favicon
28.1.8. Path Matching and Content Negotiation
28.1.9. ConfigurableWebBindingInitializer
28.1.10. Template Engines
28.1.11. Error Handling
Custom Error Pages
Mapping Error Pages outside of Spring MVC
28.1.12. Spring HATEOAS
28.1.13. CORS Support
28.2. The “Spring WebFlux Framework”
28.2.1. Spring WebFlux Auto-configuration
28.2.2. HTTP Codecs with HttpMessageReaders and HttpMessageWriters
28.2.3. Static Content
28.2.4. Template Engines
28.2.5. Error Handling
Custom Error Pages
28.2.6. Web Filters
28.3. JAX-RS and Jersey
28.4. Embedded Servlet Container Support
28.4.1. Servlets, Filters, and listeners
Registering Servlets, Filters, and Listeners as Spring Beans
28.4.2. Servlet Context Initialization
Scanning for Servlets, Filters, and listeners
28.4.3. The ServletWebServerApplicationContext
28.4.4. Customizing Embedded Servlet Containers
Programmatic Customization
Customizing ConfigurableServletWebServerFactory Directly
28.4.5. JSP Limitations
29. Security
29.1. MVC Security
29.2. WebFlux Security
29.3. OAuth2
29.3.1. Client
29.3.2. Server
29.4. Actuator Security
29.4.1. Cross Site Request Forgery Protection
30. Working with SQL Databases
30.1. Configure a DataSource
30.1.1. Embedded Database Support
30.1.2. Connection to a Production Database
30.1.3. Connection to a JNDI DataSource
30.2. Using JdbcTemplate
30.3. JPA and “Spring Data”
30.3.1. Entity Classes
30.3.2. Spring Data JPA Repositories
30.3.3. Creating and Dropping JPA Databases
30.3.4. Open EntityManager in View
30.4. Using H2’s Web Console
30.4.1. Changing the H2 Console’s Path
30.5. Using jOOQ
30.5.1. Code Generation
30.5.2. Using DSLContext
30.5.3. jOOQ SQL Dialect
30.5.4. Customizing jOOQ
31. Working with NoSQL Technologies
31.1. Redis
31.1.1. Connecting to Redis
31.2. MongoDB
31.2.1. Connecting to a MongoDB Database
31.2.2. MongoTemplate
31.2.3. Spring Data MongoDB Repositories
31.2.4. Embedded Mongo
31.3. Neo4j
31.3.1. Connecting to a Neo4j Database
31.3.2. Using the Embedded Mode
31.3.3. Neo4jSession
31.3.4. Spring Data Neo4j Repositories
31.4. Gemfire
31.5. Solr
31.5.1. Connecting to Solr
31.5.2. Spring Data Solr Repositories
31.6. Elasticsearch
31.6.1. Connecting to Elasticsearch by Using Jest
31.6.2. Connecting to Elasticsearch by Using Spring Data
31.6.3. Spring Data Elasticsearch Repositories
31.7. Cassandra
31.7.1. Connecting to Cassandra
31.7.2. Spring Data Cassandra Repositories
31.8. Couchbase
31.8.1. Connecting to Couchbase
31.8.2. Spring Data Couchbase Repositories
31.9. LDAP
31.9.1. Connecting to an LDAP Server
31.9.2. Spring Data LDAP Repositories
31.9.3. Embedded In-memory LDAP Server
31.10. InfluxDB
31.10.1. Connecting to InfluxDB
32. Caching
32.1. Supported Cache Providers
32.1.1. Generic
32.1.2. JCache (JSR-107)
32.1.3. EhCache 2.x
32.1.4. Hazelcast
32.1.5. Infinispan
32.1.6. Couchbase
32.1.7. Redis
32.1.8. Caffeine
32.1.9. Simple
32.1.10. None
33. Messaging
33.1. JMS
33.1.1. ActiveMQ Support
33.1.2. Artemis Support
33.1.3. Using a JNDI ConnectionFactory
33.1.4. Sending a Message
33.1.5. Receiving a Message
33.2. AMQP
33.2.1. RabbitMQ support
33.2.2. Sending a Message
33.2.3. Receiving a Message
33.3. Apache Kafka Support
33.3.1. Sending a Message
33.3.2. Receiving a Message
33.3.3. Additional Kafka Properties
34. Calling REST Services with RestTemplate
34.1. RestTemplate Customization
35. Calling REST Services with WebClient
35.1. WebClient Customization
36. Validation
37. Sending Email
38. Distributed Transactions with JTA
38.1. Using an Atomikos Transaction Manager
38.2. Using a Bitronix Transaction Manager
38.3. Using a Narayana Transaction Manager
38.4. Using a Java EE Managed Transaction Manager
38.5. Mixing XA and Non-XA JMS Connections
38.6. Supporting an Alternative Embedded Transaction Manager
39. Hazelcast
40. Quartz Scheduler
41. Spring Integration
42. Spring Session
43. Monitoring and Management over JMX
44. Testing
44.1. Test Scope Dependencies
44.2. Testing Spring Applications
44.3. Testing Spring Boot Applications
44.3.1. Detecting Web Application Type
44.3.2. Detecting Test Configuration
44.3.3. Excluding Test Configuration
44.3.4. Testing with a mock environment
44.3.5. Testing with a running server
44.3.6. Using JMX
44.3.7. Mocking and Spying Beans
44.3.8. Auto-configured Tests
44.3.9. Auto-configured JSON Tests
44.3.10. Auto-configured Spring MVC Tests
44.3.11. Auto-configured Spring WebFlux Tests
44.3.12. Auto-configured Data JPA Tests
44.3.13. Auto-configured JDBC Tests
44.3.14. Auto-configured jOOQ Tests
44.3.15. Auto-configured Data MongoDB Tests
44.3.16. Auto-configured Data Neo4j Tests
44.3.17. Auto-configured Data Redis Tests
44.3.18. Auto-configured Data LDAP Tests
44.3.19. Auto-configured REST Clients
44.3.20. Auto-configured Spring REST Docs Tests
Auto-configured Spring REST Docs Tests with Mock MVC
Auto-configured Spring REST Docs Tests with REST Assured
44.3.21. Additional Auto-configuration and Slicing
44.3.22. User Configuration and Slicing
44.3.23. Using Spock to Test Spring Boot Applications
44.4. Test Utilities
44.4.1. ConfigFileApplicationContextInitializer
44.4.2. TestPropertyValues
44.4.3. OutputCapture
44.4.4. TestRestTemplate
45. WebSockets
46. Web Services
47. Creating Your Own Auto-configuration
47.1. Understanding Auto-configured Beans
47.2. Locating Auto-configuration Candidates
47.3. Condition Annotations
47.3.1. Class Conditions
47.3.2. Bean Conditions
47.3.3. Property Conditions
47.3.4. Resource Conditions
47.3.5. Web Application Conditions
47.3.6. SpEL Expression Conditions
47.4. Testing your Auto-configuration
47.4.1. Simulating a Web Context
47.4.2. Overriding the Classpath
47.5. Creating Your Own Starter
47.5.1. Naming
47.5.2. autoconfigure Module
47.5.3. Starter Module
48. Kotlin support
48.1. Requirements
48.2. Null-safety
48.3. Kotlin API
48.3.1. runApplication
48.3.2. Extensions
48.4. Dependency management
48.5. @ConfigurationProperties
48.6. Testing
48.7. Resources
48.7.1. Further reading
48.7.2. Examples
49. What to Read Next
V. Spring Boot Actuator: Production-ready features
50. Enabling Production-ready Features
51. Endpoints
51.1. Enabling Endpoints
51.2. Exposing Endpoints
51.3. Securing HTTP Endpoints
51.4. Configuring Endpoints
51.5. Hypermedia for Actuator Web Endpoints
51.6. CORS Support
51.7. Implementing Custom Endpoints
51.7.1. Receiving Input
Input type conversion
51.7.2. Custom Web Endpoints
Web Endpoint Request Predicates
Path
HTTP method
Consumes
Produces
Web Endpoint Response Status
Web Endpoint Range Requests
Web Endpoint Security
51.7.3. Servlet endpoints
51.7.4. Controller endpoints
51.8. Health Information
51.8.1. Auto-configured HealthIndicators
51.8.2. Writing Custom HealthIndicators
51.8.3. Reactive Health Indicators
51.8.4. Auto-configured ReactiveHealthIndicators
51.9. Application Information
51.9.1. Auto-configured InfoContributors
51.9.2. Custom Application Information
51.9.3. Git Commit Information
51.9.4. Build Information
51.9.5. Writing Custom InfoContributors
52. Monitoring and Management over HTTP
52.1. Customizing the Management Endpoint Paths
52.2. Customizing the Management Server Port
52.3. Configuring Management-specific SSL
52.4. Customizing the Management Server Address
52.5. Disabling HTTP Endpoints
53. Monitoring and Management over JMX
53.1. Customizing MBean Names
53.2. Disabling JMX Endpoints
53.3. Using Jolokia for JMX over HTTP
53.3.1. Customizing Jolokia
53.3.2. Disabling Jolokia
54. Loggers
54.1. Configure a Logger
55. Metrics
55.1. Getting started
55.2. Supported monitoring systems
55.2.1. Atlas
55.2.2. Datadog
55.2.3. Ganglia
55.2.4. Graphite
55.2.5. Influx
55.2.6. JMX
55.2.7. New Relic
55.2.8. Prometheus
55.2.9. SignalFx
55.2.10. Simple
55.2.11. StatsD
55.2.12. Wavefront
55.3. Supported Metrics
55.3.1. Spring MVC Metrics
55.3.2. Spring WebFlux Metrics
55.3.3. RestTemplate Metrics
55.3.4. Cache Metrics
55.3.5. DataSource Metrics
55.3.6. RabbitMQ Metrics
55.4. Registering custom metrics
55.5. Customizing individual metrics
55.5.1. Per-meter properties
55.6. Metrics endpoint
56. Auditing
57. HTTP Tracing
57.1. Custom HTTP tracing
58. Process Monitoring
58.1. Extending Configuration
58.2. Programmatically
59. Cloud Foundry Support
59.1. Disabling Extended Cloud Foundry Actuator Support
59.2. Cloud Foundry Self-signed Certificates
59.3. Custom context path
60. What to Read Next
VI. Deploying Spring Boot Applications
61. Deploying to the Cloud
61.1. Cloud Foundry
61.1.1. Binding to Services
61.2. Heroku
61.3. OpenShift
61.4. Amazon Web Services (AWS)
61.4.1. AWS Elastic Beanstalk
Using the Tomcat Platform
Using the Java SE Platform
61.4.2. Summary
61.5. Boxfuse and Amazon Web Services
61.6. Google Cloud
62. Installing Spring Boot Applications
62.1. Supported Operating Systems
62.2. Unix/Linux Services
62.2.1. Installation as an init.d Service (System V)
Securing an init.d Service
62.2.2. Installation as a systemd Service
62.2.3. Customizing the Startup Script
Customizing the Start Script when It Is Written
Customizing a Script When It Runs
62.3. Microsoft Windows Services
63. What to Read Next
VII. Spring Boot CLI
64. Installing the CLI
65. Using the CLI
65.1. Running Applications with the CLI
65.1.1. Deduced “grab” Dependencies
65.1.2. Deduced “grab” Coordinates
65.1.3. Default Import Statements
65.1.4. Automatic Main Method
65.1.5. Custom Dependency Management
65.2. Applications with Multiple Source Files
65.3. Packaging Your Application
65.4. Initialize a New Project
65.5. Using the Embedded Shell
65.6. Adding Extensions to the CLI
66. Developing Applications with the Groovy Beans DSL
67. Configuring the CLI with settings.xml
68. What to Read Next
VIII. Build tool plugins
69. Spring Boot Maven Plugin
69.1. Including the Plugin
69.2. Packaging Executable Jar and War Files
70. Spring Boot Gradle Plugin
71. Spring Boot AntLib Module
71.1. Spring Boot Ant Tasks
71.1.1. spring-boot:exejar
71.1.2. Examples
71.2. spring-boot:findmainclass
71.2.1. Examples
72. Supporting Other Build Systems
72.1. Repackaging Archives
72.2. Nested Libraries
72.3. Finding a Main Class
72.4. Example Repackage Implementation
73. What to Read Next
IX. ‘How-to’ guides
74. Spring Boot Application
74.1. Create Your Own FailureAnalyzer
74.2. Troubleshoot Auto-configuration
74.3. Customize the Environment or ApplicationContext Before It Starts
74.4. Build an ApplicationContext Hierarchy (Adding a Parent or Root Context)
74.5. Create a Non-web Application
75. Properties and Configuration
75.1. Automatically Expand Properties at Build Time
75.1.1. Automatic Property Expansion Using Maven
75.1.2. Automatic Property Expansion Using Gradle
75.2. Externalize the Configuration of SpringApplication
75.3. Change the Location of External Properties of an Application
75.4. Use ‘Short’ Command Line Arguments
75.5. Use YAML for External Properties
75.6. Set the Active Spring Profiles
75.7. Change Configuration Depending on the Environment
75.8. Discover Built-in Options for External Properties
76. Embedded Web Servers
76.1. Use Another Web Server
76.2. Disabling the Web Server
76.3. Change the HTTP Port
76.4. Use a Random Unassigned HTTP Port
76.5. Discover the HTTP Port at Runtime
76.6. Enable HTTP Response Compression
76.7. Configure SSL
76.8. Configure HTTP/2
76.8.1. HTTP/2 with Undertow
76.8.2. HTTP/2 with Jetty
76.8.3. HTTP/2 with Tomcat
76.9. Configure the Web Server
76.10. Add a Servlet, Filter, or Listener to an Application
76.10.1. Add a Servlet, Filter, or Listener by Using a Spring Bean
Disable Registration of a Servlet or Filter
76.10.2. Add Servlets, Filters, and Listeners by Using Classpath Scanning
76.11. Configure Access Logging
76.12. Running Behind a Front-end Proxy Server
76.12.1. Customize Tomcat’s Proxy Configuration
76.13. Enable Multiple Connectors with Tomcat
76.14. Use Tomcat’s LegacyCookieProcessor
76.15. Enable Multiple Listeners with Undertow
76.16. Create WebSocket Endpoints Using @ServerEndpoint
77. Spring MVC
77.1. Write a JSON REST Service
77.2. Write an XML REST Service
77.3. Customize the Jackson ObjectMapper
77.4. Customize the @ResponseBody Rendering
77.5. Handling Multipart File Uploads
77.6. Switch Off the Spring MVC DispatcherServlet
77.7. Switch off the Default MVC Configuration
77.8. Customize ViewResolvers
78. Jersey
78.1. Secure Jersey endpoints with Spring Security
79. HTTP Clients
79.1. Configure RestTemplate to Use a Proxy
80. Logging
80.1. Configure Logback for Logging
80.1.1. Configure Logback for File-only Output
80.2. Configure Log4j for Logging
80.2.1. Use YAML or JSON to Configure Log4j 2
81. Data Access
81.1. Configure a Custom DataSource
81.2. Configure Two DataSources
81.3. Use Spring Data Repositories
81.4. Separate @Entity Definitions from Spring Configuration
81.5. Configure JPA Properties
81.6. Configure Hibernate Naming Strategy
81.7. Use a Custom EntityManagerFactory
81.8. Use Two EntityManagers
81.9. Use a Traditional persistence.xml File
81.10. Use Spring Data JPA and Mongo Repositories
81.11. Customize Spring Data’s Web Support
81.12. Expose Spring Data Repositories as REST Endpoint
81.13. Configure a Component that is Used by JPA
81.14. Configure jOOQ with Two DataSources
82. Database Initialization
82.1. Initialize a Database Using JPA
82.2. Initialize a Database Using Hibernate
82.3. Initialize a Database
82.4. Initialize a Spring Batch Database
82.5. Use a Higher-level Database Migration Tool
82.5.1. Execute Flyway Database Migrations on Startup
82.5.2. Execute Liquibase Database Migrations on Startup
83. Messaging
83.1. Disable Transacted JMS Session
84. Batch Applications
84.1. Execute Spring Batch Jobs on Startup
85. Actuator
85.1. Change the HTTP Port or Address of the Actuator Endpoints
85.2. Customize the ‘whitelabel’ Error Page
85.3. Sanitize sensible values
86. Security
86.1. Switch off the Spring Boot Security Configuration
86.2. Change the UserDetailsService and Add User Accounts
86.3. Enable HTTPS When Running behind a Proxy Server
87. Hot Swapping
87.1. Reload Static Content
87.2. Reload Templates without Restarting the Container
87.2.1. Thymeleaf Templates
87.2.2. FreeMarker Templates
87.2.3. Groovy Templates
87.3. Fast Application Restarts
87.4. Reload Java Classes without Restarting the Container
88. Build
88.1. Generate Build Information
88.2. Generate Git Information
88.3. Customize Dependency Versions
88.4. Create an Executable JAR with Maven
88.5. Use a Spring Boot Application as a Dependency
88.6. Extract Specific Libraries When an Executable Jar Runs
88.7. Create a Non-executable JAR with Exclusions
88.8. Remote Debug a Spring Boot Application Started with Maven
88.9. Build an Executable Archive from Ant without Using spring-boot-antlib
89. Traditional Deployment
89.1. Create a Deployable War File
89.2. Convert an Existing Application to Spring Boot
89.3. Deploying a WAR to WebLogic
89.4. Use Jedis Instead of Lettuce
X. Appendices
A. Common application properties
B. Configuration Metadata
B.1. Metadata Format
B.1.1. Group Attributes
B.1.2. Property Attributes
B.1.3. Hint Attributes
B.1.4. Repeated Metadata Items
B.2. Providing Manual Hints
B.2.1. Value Hint
B.2.2. Value Providers
Any
Class Reference
Handle As
Logger Name
Spring Bean Reference
Spring Profile Name
B.3. Generating Your Own Metadata by Using the Annotation Processor
B.3.1. Nested Properties
B.3.2. Adding Additional Metadata
C. Auto-configuration classes
C.1. From the “spring-boot-autoconfigure” module
C.2. From the “spring-boot-actuator-autoconfigure” module
D. Test auto-configuration annotations
E. The Executable Jar Format
E.1. Nested JARs
E.1.1. The Executable Jar File Structure
E.1.2. The Executable War File Structure
E.2. Spring Boot’s “JarFile” Class
E.2.1. Compatibility with the Standard Java “JarFile”
E.3. Launching Executable Jars
E.3.1. Launcher Manifest
E.3.2. Exploded Archives
E.4. PropertiesLauncher Features
E.5. Executable Jar Restrictions
E.6. Alternative Single Jar Solutions
F. Dependency versions
   Next
   Part I. Spring Boot Documentation