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

1.3.2.RELEASE

Copyright © 2013-2016

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. Starter POMs
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. Customizing the Banner
23.2. Customizing SpringApplication
23.3. Fluent builder API
23.4. Application events and listeners
23.5. Web environment
23.6. Accessing application arguments
23.7. Using the ApplicationRunner or CommandLineRunner
23.8. Application exit
23.9. 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.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
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. MessageCodesResolver
27.1.4. Static Content
27.1.5. ConfigurableWebBindingInitializer
27.1.6. Template engines
27.1.7. Error Handling
Error Handling on WebSphere Application Server
27.1.8. Spring HATEOAS
27.1.9. 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.4. Using H2’s web console
29.4.1. Changing the H2 console’s path
29.4.2. Securing the H2 console
30. Using jOOQ
30.1. Code Generation
30.2. Using DSLContext
30.3. 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. Gemfire
31.4. Solr
31.4.1. Connecting to Solr
31.4.2. Spring Data Solr repositories
31.5. Elasticsearch
31.5.1. Connecting to Elasticsearch
31.5.2. Spring Data Elasticsearch repositories
31.6. Cassandra
31.6.1. Connecting to Cassandra
31.6.2. Spring Data Cassandra repositories
32. Caching
32.1. Supported cache providers
32.1.1. Generic
32.1.2. JCache
32.1.3. EhCache 2.x
32.1.4. Hazelcast
32.1.5. Infinispan
32.1.6. Redis
32.1.7. Guava
32.1.8. Simple
33. Messaging
33.1. JMS
33.1.1. ActiveMQ support
33.1.2. Artemis support
33.1.3. HornetQ support
33.1.4. Using a JNDI ConnectionFactory
33.1.5. Sending a message
33.1.6. Receiving a message
33.2. AMQP
33.2.1. RabbitMQ support
33.2.2. Sending a message
33.2.3. Receiving a message
34. Sending email
35. Distributed Transactions with JTA
35.1. Using an Atomikos transaction manager
35.2. Using a Bitronix transaction manager
35.3. Using a Java EE managed transaction manager
35.4. Mixing XA and non-XA JMS connections
35.5. Supporting an alternative embedded transaction manager
36. Hazelcast
37. Spring Integration
38. Spring Session
39. Monitoring and management over JMX
40. Testing
40.1. Test scope dependencies
40.2. Testing Spring applications
40.3. Testing Spring Boot applications
40.3.1. Using Spock to test Spring Boot applications
40.4. Test utilities
40.4.1. ConfigFileApplicationContextInitializer
40.4.2. EnvironmentTestUtils
40.4.3. OutputCapture
40.4.4. TestRestTemplate
41. Creating your own auto-configuration
41.1. Understanding auto-configured beans
41.2. Locating auto-configuration candidates
41.3. Condition annotations
41.3.1. Class conditions
41.3.2. Bean conditions
41.3.3. Property conditions
41.3.4. Resource conditions
41.3.5. Web application conditions
41.3.6. SpEL expression conditions
41.4. Creating your own starter
41.4.1. Naming
41.4.2. Autoconfigure module
41.4.3. Starter module
42. WebSockets
43. What to read next
V. Spring Boot Actuator: Production-ready features
44. Enabling production-ready features
45. Endpoints
45.1. Customizing endpoints
45.2. Hypermedia for actuator MVC endpoints
45.3. CORS support
45.4. Adding custom endpoints
45.5. Health information
45.6. Security with HealthIndicators
45.6.1. Auto-configured HealthIndicators
45.6.2. Writing custom HealthIndicators
45.7. Custom application info information
45.7.1. Automatically expand info properties at build time
Automatic property expansion using Maven
Automatic property expansion using Gradle
45.7.2. Git commit information
46. Monitoring and management over HTTP
46.1. Securing sensitive endpoints
46.2. Customizing the management endpoint paths
46.3. Customizing the management server port
46.4. Customizing the management server address
46.5. Disabling HTTP endpoints
46.6. HTTP health endpoint access restrictions
47. Monitoring and management over JMX
47.1. Customizing MBean names
47.2. Disabling JMX endpoints
47.3. Using Jolokia for JMX over HTTP
47.3.1. Customizing Jolokia
47.3.2. Disabling Jolokia
48. Monitoring and management using a remote shell
48.1. Connecting to the remote shell
48.1.1. Remote shell credentials
48.2. Extending the remote shell
48.2.1. Remote shell commands
48.2.2. Remote shell plugins
49. Metrics
49.1. System metrics
49.2. DataSource metrics
49.3. Cache metrics
49.4. Tomcat session metrics
49.5. Recording your own metrics
49.6. Adding your own public metrics
49.7. Special features with Java 8
49.8. Metric writers, exporters and aggregation
49.8.1. Example: Export to Redis
49.8.2. Example: Export to Open TSDB
49.8.3. Example: Export to Statsd
49.8.4. Example: Export to JMX
49.9. Aggregating metrics from multiple sources
49.10. Dropwizard Metrics
49.11. Message channel integration
50. Auditing
51. Tracing
51.1. Custom tracing
52. Process monitoring
52.1. Extend configuration
52.2. Programmatically
53. What to read next
VI. Deploying Spring Boot applications
54. Deploying to the cloud
54.1. Cloud Foundry
54.1.1. Binding to services
54.2. Heroku
54.3. OpenShift
54.4. Boxfuse and Amazon Web Services
54.5. Google App Engine
55. Installing Spring Boot applications
55.1. Unix/Linux services
55.1.1. Installation as an init.d service (System V)
Securing an init.d service
55.1.2. Installation as a systemd service
55.1.3. Customizing the startup script
55.1.4. Customizing the startup script with a conf file
56. Microsoft Windows services
57. What to read next
VII. Spring Boot CLI
58. Installing the CLI
59. Using the CLI
59.1. Running applications using the CLI
59.1.1. Deduced “grab” dependencies
59.1.2. Deduced “grab” coordinates
59.1.3. Default import statements
59.1.4. Automatic main method
59.1.5. Custom dependency management
59.2. Testing your code
59.3. Applications with multiple source files
59.4. Packaging your application
59.5. Initialize a new project
59.6. Using the embedded shell
59.7. Adding extensions to the CLI
60. Developing application with the Groovy beans DSL
61. Configuring the CLI with settings.xml
62. What to read next
VIII. Build tool plugins
63. Spring Boot Maven plugin
63.1. Including the plugin
63.2. Packaging executable jar and war files
64. Spring Boot Gradle plugin
64.1. Including the plugin
64.2. Gradle dependency management
64.3. Packaging executable jar and war files
64.4. Running a project in-place
64.5. Spring Boot plugin configuration
64.6. Repackage configuration
64.7. Repackage with custom Gradle configuration
64.7.1. Configuration options
64.8. Understanding how the Gradle plugin works
64.9. Publishing artifacts to a Maven repository using Gradle
64.9.1. Configuring Gradle to produce a pom that inherits dependency management
64.9.2. Configuring Gradle to produce a pom that imports dependency management
65. Spring Boot AntLib module
65.1. Spring Boot Ant tasks
65.1.1. spring-boot:exejar
65.1.2. Examples
65.2. spring-boot:findmainclass
65.2.1. Examples
66. Supporting other build systems
66.1. Repackaging archives
66.2. Nested libraries
66.3. Finding a main class
66.4. Example repackage implementation
67. What to read next
IX. ‘How-to’ guides
68. Spring Boot application
68.1. Troubleshoot auto-configuration
68.2. Customize the Environment or ApplicationContext before it starts
68.3. Build an ApplicationContext hierarchy (adding a parent or root context)
68.4. Create a non-web application
69. Properties & configuration
69.1. Externalize the configuration of SpringApplication
69.2. Change the location of external properties of an application
69.3. Use ‘short’ command line arguments
69.4. Use YAML for external properties
69.5. Set the active Spring profiles
69.6. Change configuration depending on the environment
69.7. Discover built-in options for external properties
70. Embedded servlet containers
70.1. Add a Servlet, Filter or Listener to an application
70.1.1. Add a Servlet, Filter or Listener using a Spring bean
Disable registration of a Servlet or Filter
70.1.2. Add Servlets, Filters, and Listeners using classpath scanning
70.2. Change the HTTP port
70.3. Use a random unassigned HTTP port
70.4. Discover the HTTP port at runtime
70.5. Configure SSL
70.6. Use behind a front-end proxy server
70.6.1. Customize Tomcat’s proxy configuration
70.7. Configure Tomcat
70.8. Enable Multiple Connectors with Tomcat
70.9. Use Jetty instead of Tomcat
70.10. Configure Jetty
70.11. Use Undertow instead of Tomcat
70.12. Configure Undertow
70.13. Enable Multiple Listeners with Undertow
70.14. Use Tomcat 7
70.14.1. Use Tomcat 7 with Maven
70.14.2. Use Tomcat 7 with Gradle
70.15. Use Jetty 8
70.15.1. Use Jetty 8 with Maven
70.15.2. Use Jetty 8 with Gradle
70.16. Create WebSocket endpoints using @ServerEndpoint
70.17. Enable HTTP response compression
71. Spring MVC
71.1. Write a JSON REST service
71.2. Write an XML REST service
71.3. Customize the Jackson ObjectMapper
71.4. Customize the @ResponseBody rendering
71.5. Handling Multipart File Uploads
71.6. Switch off the Spring MVC DispatcherServlet
71.7. Switch off the Default MVC configuration
71.8. Customize ViewResolvers
71.9. Velocity
72. Logging
72.1. Configure Logback for logging
72.1.1. Configure logback for file only output
72.2. Configure Log4j for logging
72.2.1. Use YAML or JSON to configure Log4j 2
73. Data Access
73.1. Configure a DataSource
73.2. Configure Two DataSources
73.3. Use Spring Data repositories
73.4. Separate @Entity definitions from Spring configuration
73.5. Configure JPA properties
73.6. Use a custom EntityManagerFactory
73.7. Use Two EntityManagers
73.8. Use a traditional persistence.xml
73.9. Use Spring Data JPA and Mongo repositories
73.10. Expose Spring Data repositories as REST endpoint
74. Database initialization
74.1. Initialize a database using JPA
74.2. Initialize a database using Hibernate
74.3. Initialize a database using Spring JDBC
74.4. Initialize a Spring Batch database
74.5. Use a higher level database migration tool
74.5.1. Execute Flyway database migrations on startup
74.5.2. Execute Liquibase database migrations on startup
75. Batch applications
75.1. Execute Spring Batch jobs on startup
76. Actuator
76.1. Change the HTTP port or address of the actuator endpoints
76.2. Customize the ‘whitelabel’ error page
76.3. Actuator and Jersey
77. Security
77.1. Switch off the Spring Boot security configuration
77.2. Change the AuthenticationManager and add user accounts
77.3. Enable HTTPS when running behind a proxy server
78. Hot swapping
78.1. Reload static content
78.2. Reload templates without restarting the container
78.2.1. Thymeleaf templates
78.2.2. FreeMarker templates
78.2.3. Groovy templates
78.2.4. Velocity templates
78.3. Fast application restarts
78.4. Reload Java classes without restarting the container
78.4.1. Configuring Spring Loaded for use with Maven
78.4.2. Configuring Spring Loaded for use with Gradle and IntelliJ IDEA
79. Build
79.1. Customize dependency versions
79.2. Create an executable JAR with Maven
79.3. Create an additional executable JAR
79.4. Extract specific libraries when an executable jar runs
79.5. Create a non-executable JAR with exclusions
79.6. Remote debug a Spring Boot application started with Maven
79.7. Remote debug a Spring Boot application started with Gradle
79.8. Build an executable archive from Ant without using spring-boot-antlib
79.9. How to use Java 6
79.9.1. Embedded servlet container compatibility
79.9.2. JTA API compatibility
80. Traditional deployment
80.1. Create a deployable war file
80.2. Create a deployable war file for older servlet containers
80.3. Convert an existing application to Spring Boot
80.4. Deploying a WAR to WebLogic
80.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. 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
   Next
   Part I. Spring Boot Documentation