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

1.5.13.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. 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. Changing the Java version
13.2.4. 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
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. Excluding resources
20.2.2. Watching additional paths
20.2.3. Disabling restart
20.2.4. Using a trigger file
20.2.5. Customizing the restart classloader
20.2.6. 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
20.5.3. Remote debug tunnel
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. Using YAML instead of Properties
24.6.1. Loading YAML
24.6.2. Exposing YAML as properties in the Spring Environment
24.6.3. Multi-profile YAML documents
24.6.4. YAML shortcomings
24.6.5. Merging YAML lists
24.7. Type-safe Configuration Properties
24.7.1. Third-party configuration
24.7.2. Relaxed binding
24.7.3. Properties conversion
24.7.4. @ConfigurationProperties Validation
24.7.5. @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. Developing web applications
27.1. The ‘Spring Web MVC framework’
27.1.1. Spring MVC auto-configuration
27.1.2. HttpMessageConverters
27.1.3. Custom JSON Serializers and Deserializers
27.1.4. MessageCodesResolver
27.1.5. Static Content
27.1.6. Custom Favicon
27.1.7. ConfigurableWebBindingInitializer
27.1.8. Template engines
27.1.9. Error Handling
Custom error pages
Mapping error pages outside of Spring MVC
Error Handling on WebSphere Application Server
27.1.10. Spring HATEOAS
27.1.11. CORS support
27.2. JAX-RS and Jersey
27.3. Embedded servlet container support
27.3.1. Servlets, Filters, and listeners
Registering Servlets, Filters, and listeners as Spring beans
27.3.2. Servlet Context Initialization
Scanning for Servlets, Filters, and listeners
27.3.3. The EmbeddedWebApplicationContext
27.3.4. Customizing embedded servlet containers
Programmatic customization
Customizing ConfigurableEmbeddedServletContainer directly
27.3.5. JSP limitations
28. Security
28.1. OAuth2
28.1.1. Authorization Server
28.1.2. Resource Server
28.2. Token Type in User Info
28.3. Customizing the User Info RestTemplate
28.3.1. Client
28.3.2. Single Sign On
28.4. Actuator Security
29. Working with SQL databases
29.1. Configure a DataSource
29.1.1. Embedded Database Support
29.1.2. Connection to a production database
29.1.3. Connection to a JNDI DataSource
29.2. Using JdbcTemplate
29.3. JPA and ‘Spring Data’
29.3.1. Entity Classes
29.3.2. Spring Data JPA Repositories
29.3.3. Creating and dropping JPA databases
29.3.4. Open EntityManager in View
29.4. Using H2’s web console
29.4.1. Changing the H2 console’s path
29.4.2. Securing the H2 console
29.5. Using jOOQ
29.5.1. Code Generation
29.5.2. Using DSLContext
29.5.3. Customizing jOOQ
30. Working with NoSQL technologies
30.1. Redis
30.1.1. Connecting to Redis
30.2. MongoDB
30.2.1. Connecting to a MongoDB database
30.2.2. MongoTemplate
30.2.3. Spring Data MongoDB repositories
30.2.4. Embedded Mongo
30.3. Neo4j
30.3.1. Connecting to a Neo4j database
30.3.2. Using the embedded mode
30.3.3. Neo4jSession
30.3.4. Spring Data Neo4j repositories
30.3.5. Repository example
30.4. Gemfire
30.5. Solr
30.5.1. Connecting to Solr
30.5.2. Spring Data Solr repositories
30.6. Elasticsearch
30.6.1. Connecting to Elasticsearch using Jest
30.6.2. Connecting to Elasticsearch using Spring Data
30.6.3. Spring Data Elasticsearch repositories
30.7. Cassandra
30.7.1. Connecting to Cassandra
30.7.2. Spring Data Cassandra repositories
30.8. Couchbase
30.8.1. Connecting to Couchbase
30.8.2. Spring Data Couchbase repositories
30.9. LDAP
30.9.1. Connecting to an LDAP server
30.9.2. Spring Data LDAP repositories
30.9.3. Embedded in-memory LDAP server
31. Caching
31.1. Supported cache providers
31.1.1. Generic
31.1.2. JCache (JSR-107)
31.1.3. EhCache 2.x
31.1.4. Hazelcast
31.1.5. Infinispan
31.1.6. Couchbase
31.1.7. Redis
31.1.8. Caffeine
31.1.9. Guava (deprecated)
31.1.10. Simple
31.1.11. None
32. Messaging
32.1. JMS
32.1.1. ActiveMQ support
32.1.2. Artemis support
32.1.3. Using a JNDI ConnectionFactory
32.1.4. Sending a message
32.1.5. Receiving a message
32.2. AMQP
32.2.1. RabbitMQ support
32.2.2. Sending a message
32.2.3. Receiving a message
32.3. Apache Kafka Support
32.3.1. Sending a Message
32.3.2. Receiving a Message
32.3.3. Additional Kafka Properties
33. Calling REST services
33.1. RestTemplate customization
34. Validation
35. Sending email
36. Distributed Transactions with JTA
36.1. Using an Atomikos transaction manager
36.2. Using a Bitronix transaction manager
36.3. Using a Narayana transaction manager
36.4. Using a Java EE managed transaction manager
36.5. Mixing XA and non-XA JMS connections
36.6. Supporting an alternative embedded transaction manager
37. Hazelcast
38. Spring Integration
39. Spring Session
40. Monitoring and management over JMX
41. Testing
41.1. Test scope dependencies
41.2. Testing Spring applications
41.3. Testing Spring Boot applications
41.3.1. Detecting test configuration
41.3.2. Excluding test configuration
41.3.3. Working with random ports
41.3.4. Using JMX
41.3.5. Mocking and spying beans
41.3.6. Auto-configured tests
41.3.7. Auto-configured JSON tests
41.3.8. Auto-configured Spring MVC tests
41.3.9. Auto-configured Data JPA tests
41.3.10. Auto-configured JDBC tests
41.3.11. Auto-configured Data MongoDB tests
41.3.12. Auto-configured REST clients
41.3.13. Auto-configured Spring REST Docs tests
41.3.14. User configuration and slicing
41.3.15. Using Spock to test Spring Boot applications
41.4. Test utilities
41.4.1. ConfigFileApplicationContextInitializer
41.4.2. EnvironmentTestUtils
41.4.3. OutputCapture
41.4.4. TestRestTemplate
42. WebSockets
43. Web Services
44. Creating your own auto-configuration
44.1. Understanding auto-configured beans
44.2. Locating auto-configuration candidates
44.3. Condition annotations
44.3.1. Class conditions
44.3.2. Bean conditions
44.3.3. Property conditions
44.3.4. Resource conditions
44.3.5. Web application conditions
44.3.6. SpEL expression conditions
44.4. Creating your own starter
44.4.1. Naming
44.4.2. Autoconfigure module
44.4.3. Starter module
45. What to read next
V. Spring Boot Actuator: Production-ready features
46. Enabling production-ready features
47. Endpoints
47.1. Customizing endpoints
47.2. Hypermedia for actuator MVC endpoints
47.3. CORS support
47.4. Adding custom endpoints
47.5. Health information
47.6. Security with HealthIndicators
47.6.1. Auto-configured HealthIndicators
47.6.2. Writing custom HealthIndicators
47.7. Application information
47.7.1. Auto-configured InfoContributors
47.7.2. Custom application info information
47.7.3. Git commit information
47.7.4. Build information
47.7.5. Writing custom InfoContributors
48. Monitoring and management over HTTP
48.1. Accessing sensitive endpoints
48.2. Customizing the management endpoint paths
48.3. Customizing the management server port
48.4. Configuring management-specific SSL
48.5. Customizing the management server address
48.6. Disabling HTTP endpoints
48.7. HTTP health endpoint format and access restrictions
49. Monitoring and management over JMX
49.1. Customizing MBean names
49.2. Disabling JMX endpoints
49.3. Using Jolokia for JMX over HTTP
49.3.1. Customizing Jolokia
49.3.2. Disabling Jolokia
50. Monitoring and management using a remote shell (deprecated)
50.1. Connecting to the remote shell
50.1.1. Remote shell credentials
50.2. Extending the remote shell
50.2.1. Remote shell commands
50.2.2. Remote shell plugins
51. Loggers
51.1. Configure a Logger
52. Metrics
52.1. System metrics
52.2. DataSource metrics
52.3. Cache metrics
52.4. Tomcat session metrics
52.5. Recording your own metrics
52.6. Adding your own public metrics
52.7. Special features with Java 8
52.8. Metric writers, exporters and aggregation
52.8.1. Example: Export to Redis
52.8.2. Example: Export to Open TSDB
52.8.3. Example: Export to Statsd
52.8.4. Example: Export to JMX
52.9. Aggregating metrics from multiple sources
52.10. Dropwizard Metrics
52.11. Message channel integration
53. Auditing
54. Tracing
54.1. Custom tracing
55. Process monitoring
55.1. Extend configuration
55.2. Programmatically
56. Cloud Foundry support
56.1. Disabling extended Cloud Foundry actuator support
56.2. Cloud Foundry self signed certificates
56.3. Custom security configuration
57. What to read next
VI. Deploying Spring Boot applications
58. Deploying to the cloud
58.1. Cloud Foundry
58.1.1. Binding to services
58.2. Heroku
58.3. OpenShift
58.4. Amazon Web Services (AWS)
58.4.1. AWS Elastic Beanstalk
Using the Tomcat platform
Using the Java SE platform
Best practices
58.4.2. Summary
58.5. Boxfuse and Amazon Web Services
58.6. Google Cloud
59. Installing Spring Boot applications
59.1. Supported operating systems
59.2. Unix/Linux services
59.2.1. Installation as an init.d service (System V)
Securing an init.d service
59.2.2. Installation as a systemd service
59.2.3. Customizing the startup script
Customizing script when it’s written
Customizing script when it runs
59.3. Microsoft Windows services
60. What to read next
VII. Spring Boot CLI
61. Installing the CLI
62. Using the CLI
62.1. Running applications using the CLI
62.1.1. Deduced “grab” dependencies
62.1.2. Deduced “grab” coordinates
62.1.3. Default import statements
62.1.4. Automatic main method
62.1.5. Custom dependency management
62.2. Testing your code
62.3. Applications with multiple source files
62.4. Packaging your application
62.5. Initialize a new project
62.6. Using the embedded shell
62.7. Adding extensions to the CLI
63. Developing application with the Groovy beans DSL
64. Configuring the CLI with settings.xml
65. What to read next
VIII. Build tool plugins
66. Spring Boot Maven plugin
66.1. Including the plugin
66.2. Packaging executable jar and war files
67. Spring Boot Gradle plugin
67.1. Including the plugin
67.2. Gradle dependency management
67.3. Packaging executable jar and war files
67.4. Running a project in-place
67.5. Spring Boot plugin configuration
67.6. Repackage configuration
67.7. Repackage with custom Gradle configuration
67.7.1. Configuration options
67.7.2. Available layouts
67.7.3. Using a custom layout
67.8. Understanding how the Gradle plugin works
67.9. Publishing artifacts to a Maven repository using Gradle
67.9.1. Configuring Gradle to produce a pom that inherits dependency management
67.9.2. Configuring Gradle to produce a pom that imports dependency management
68. Spring Boot AntLib module
68.1. Spring Boot Ant tasks
68.1.1. spring-boot:exejar
68.1.2. Examples
68.2. spring-boot:findmainclass
68.2.1. Examples
69. Supporting other build systems
69.1. Repackaging archives
69.2. Nested libraries
69.3. Finding a main class
69.4. Example repackage implementation
70. What to read next
IX. ‘How-to’ guides
71. Spring Boot application
71.1. Create your own FailureAnalyzer
71.2. Troubleshoot auto-configuration
71.3. Customize the Environment or ApplicationContext before it starts
71.4. Build an ApplicationContext hierarchy (adding a parent or root context)
71.5. Create a non-web application
72. Properties & configuration
72.1. Automatically expand properties at build time
72.1.1. Automatic property expansion using Maven
72.1.2. Automatic property expansion using Gradle
72.2. Externalize the configuration of SpringApplication
72.3. Change the location of external properties of an application
72.4. Use ‘short’ command line arguments
72.5. Use YAML for external properties
72.6. Set the active Spring profiles
72.7. Change configuration depending on the environment
72.8. Discover built-in options for external properties
73. Embedded servlet containers
73.1. Add a Servlet, Filter or Listener to an application
73.1.1. Add a Servlet, Filter or Listener using a Spring bean
Disable registration of a Servlet or Filter
73.1.2. Add Servlets, Filters, and Listeners using classpath scanning
73.2. Change the HTTP port
73.3. Use a random unassigned HTTP port
73.4. Discover the HTTP port at runtime
73.5. Configure SSL
73.6. Configure Access Logging
73.7. Use behind a front-end proxy server
73.7.1. Customize Tomcat’s proxy configuration
73.8. Configure Tomcat
73.9. Enable Multiple Connectors with Tomcat
73.10. Use Tomcat’s LegacyCookieProcessor
73.11. Use Jetty instead of Tomcat
73.12. Configure Jetty
73.13. Use Undertow instead of Tomcat
73.14. Configure Undertow
73.15. Enable Multiple Listeners with Undertow
73.16. Use Tomcat 7.x or 8.0
73.16.1. Use Tomcat 7.x or 8.0 with Maven
73.16.2. Use Tomcat 7.x or 8.0 with Gradle
73.17. Use Jetty 9.2
73.17.1. Use Jetty 9.2 with Maven
73.17.2. Use Jetty 9.2 with Gradle
73.18. Use Jetty 8
73.18.1. Use Jetty 8 with Maven
73.18.2. Use Jetty 8 with Gradle
73.19. Create WebSocket endpoints using @ServerEndpoint
73.20. Enable HTTP response compression
74. Spring MVC
74.1. Write a JSON REST service
74.2. Write an XML REST service
74.3. Customize the Jackson ObjectMapper
74.4. Customize the @ResponseBody rendering
74.5. Handling Multipart File Uploads
74.6. Switch off the Spring MVC DispatcherServlet
74.7. Switch off the Default MVC configuration
74.8. Customize ViewResolvers
74.9. Use Thymeleaf 3
75. HTTP clients
75.1. Configure RestTemplate to use a proxy
76. Logging
76.1. Configure Logback for logging
76.1.1. Configure logback for file only output
76.2. Configure Log4j for logging
76.2.1. Use YAML or JSON to configure Log4j 2
77. Data Access
77.1. Configure a custom DataSource
77.2. Configure Two DataSources
77.3. Use Spring Data repositories
77.4. Separate @Entity definitions from Spring configuration
77.5. Configure JPA properties
77.6. Configure Hibernate Naming Strategy
77.7. Use a custom EntityManagerFactory
77.8. Use Two EntityManagers
77.9. Use a traditional persistence.xml
77.10. Use Spring Data JPA and Mongo repositories
77.11. Expose Spring Data repositories as REST endpoint
77.12. Configure a component that is used by JPA
77.13. Configure jOOQ with Two DataSources
78. Database initialization
78.1. Initialize a database using JPA
78.2. Initialize a database using Hibernate
78.3. Initialize a database
78.4. Initialize a Spring Batch database
78.5. Use a higher-level database migration tool
78.5.1. Execute Flyway database migrations on startup
78.5.2. Execute Liquibase database migrations on startup
79. Messaging
79.1. Disable transacted JMS session
80. Batch applications
80.1. Execute Spring Batch jobs on startup
81. Actuator
81.1. Change the HTTP port or address of the actuator endpoints
81.2. Customize the ‘whitelabel’ error page
81.3. Actuator and Jersey
82. Security
82.1. Switch off the Spring Boot security configuration
82.2. Change the AuthenticationManager and add user accounts
82.3. Enable HTTPS when running behind a proxy server
83. Hot swapping
83.1. Reload static content
83.2. Reload templates without restarting the container
83.2.1. Thymeleaf templates
83.2.2. FreeMarker templates
83.2.3. Groovy templates
83.3. Fast application restarts
83.4. Reload Java classes without restarting the container
83.4.1. Configuring Spring Loaded for use with Maven
83.4.2. Configuring Spring Loaded for use with Gradle and IntelliJ IDEA
84. Build
84.1. Generate build information
84.2. Generate git information
84.3. Customize dependency versions
84.4. Create an executable JAR with Maven
84.5. Use a Spring Boot application as a dependency
84.6. Extract specific libraries when an executable jar runs
84.7. Create a non-executable JAR with exclusions
84.8. Remote debug a Spring Boot application started with Maven
84.9. Remote debug a Spring Boot application started with Gradle
84.10. Build an executable archive from Ant without using spring-boot-antlib
84.11. How to use Java 6
84.11.1. Embedded servlet container compatibility
84.11.2. Jackson
84.11.3. JTA API compatibility
85. Traditional deployment
85.1. Create a deployable war file
85.2. Create a deployable war file for older servlet containers
85.3. Convert an existing application to Spring Boot
85.4. Deploying a WAR to WebLogic
85.5. 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. Hint Attributes
B.1.4. Repeated meta-data items
B.2. Providing manual hints
B.2.1. Value hint
B.2.2. Value provider
Any
Class reference
Handle As
Logger name
Spring bean reference
Spring profile name
B.3. Generating your own meta-data using the annotation processor
B.3.1. Nested properties
B.3.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. 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.5.1. Zip entry compression
E.5.2. System ClassLoader
E.6. Alternative single jar solutions
F. Dependency versions
   Next
   Part I. Spring Boot Documentation