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.2.5.RELEASE

Copyright © 2013-2015

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 GVM
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. Maven
13.1.1. Inheriting the starter parent
13.1.2. Using Spring Boot without the parent POM
13.1.3. Changing the Java version
13.1.4. Using the Spring Boot Maven plugin
13.2. Gradle
13.3. Ant
13.4. 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. Packaging your application for production
21. What to read next
IV. Spring Boot features
22. SpringApplication
22.1. Customizing the Banner
22.2. Customizing SpringApplication
22.3. Fluent builder API
22.4. Application events and listeners
22.5. Web environment
22.6. Using the CommandLineRunner
22.7. Application exit
23. Externalized Configuration
23.1. Configuring random values
23.2. Accessing command line properties
23.3. Application property files
23.4. Profile-specific properties
23.5. Placeholders in properties
23.6. Using YAML instead of Properties
23.6.1. Loading YAML
23.6.2. Exposing YAML as properties in the Spring Environment
23.6.3. Multi-profile YAML documents
23.6.4. YAML shortcomings
23.7. Typesafe Configuration Properties
23.7.1. Third-party configuration
23.7.2. Relaxed binding
23.7.3. @ConfigurationProperties Validation
24. Profiles
24.1. Adding active profiles
24.2. Programmatically setting profiles
24.3. Profile specific configuration files
25. Logging
25.1. Log format
25.2. Console output
25.3. File output
25.4. Log Levels
25.5. Custom log configuration
26. Developing web applications
26.1. The ‘Spring Web MVC framework’
26.1.1. Spring MVC auto-configuration
26.1.2. HttpMessageConverters
26.1.3. MessageCodesResolver
26.1.4. Static Content
26.1.5. Template engines
26.1.6. Error Handling
Error Handling on WebSphere Application Server
26.1.7. Spring HATEOAS
26.2. JAX-RS and Jersey
26.3. Embedded servlet container support
26.3.1. Servlets and Filters
26.3.2. The EmbeddedWebApplicationContext
26.3.3. Customizing embedded servlet containers
Programmatic customization
Customizing ConfigurableEmbeddedServletContainer directly
26.3.4. JSP limitations
27. Security
28. Working with SQL databases
28.1. Configure a DataSource
28.1.1. Embedded Database Support
28.1.2. Connection to a production database
28.1.3. Connection to a JNDI DataSource
28.2. Using JdbcTemplate
28.3. JPA and ‘Spring Data’
28.3.1. Entity Classes
28.3.2. Spring Data JPA Repositories
28.3.3. Creating and dropping JPA databases
29. Working with NoSQL technologies
29.1. Redis
29.1.1. Connecting to Redis
29.2. MongoDB
29.2.1. Connecting to a MongoDB database
29.2.2. MongoTemplate
29.2.3. Spring Data MongoDB repositories
29.3. Gemfire
29.4. Solr
29.4.1. Connecting to Solr
29.4.2. Spring Data Solr repositories
29.5. Elasticsearch
29.5.1. Connecting to Elasticsearch
29.5.2. Spring Data Elasticsearch repositories
30. Messaging
30.1. JMS
30.1.1. HornetQ support
30.1.2. ActiveMQ support
30.1.3. Using a JNDI ConnectionFactory
30.1.4. Sending a message
30.1.5. Receiving a message
31. Sending email
32. Distributed Transactions with JTA
32.1. Using an Atomikos transaction manager
32.2. Using a Bitronix transaction manager
32.3. Using a Java EE managed transaction manager
32.4. Mixing XA and non-XA JMS connections
32.5. Supporting an alternative embedded transaction manager
33. Spring Integration
34. Monitoring and management over JMX
35. Testing
35.1. Test scope dependencies
35.2. Testing Spring applications
35.3. Testing Spring Boot applications
35.3.1. Using Spock to test Spring Boot applications
35.4. Test utilities
35.4.1. ConfigFileApplicationContextInitializer
35.4.2. EnvironmentTestUtils
35.4.3. OutputCapture
35.4.4. TestRestTemplate
36. Developing auto-configuration and using conditions
36.1. Understanding auto-configured beans
36.2. Locating auto-configuration candidates
36.3. Condition annotations
36.3.1. Class conditions
36.3.2. Bean conditions
36.3.3. Property conditions
36.3.4. Resource conditions
36.3.5. Web application conditions
36.3.6. SpEL expression conditions
37. WebSockets
38. What to read next
V. Spring Boot Actuator: Production-ready features
39. Enabling production-ready features
40. Endpoints
40.1. Customizing endpoints
40.2. Health information
40.3. Security with HealthIndicators
40.3.1. Auto-configured HealthIndicators
40.3.2. Writing custom HealthIndicators
40.4. Custom application info information
40.4.1. Automatically expand info properties at build time
Automatic property expansion using Maven
Automatic property expansion using Gradle
40.4.2. Git commit information
41. Monitoring and management over HTTP
41.1. Securing sensitive endpoints
41.2. Customizing the management server context path
41.3. Customizing the management server port
41.4. Customizing the management server address
41.5. Disabling HTTP endpoints
41.6. HTTP health endpoint access restrictions
42. Monitoring and management over JMX
42.1. Customizing MBean names
42.2. Disabling JMX endpoints
42.3. Using Jolokia for JMX over HTTP
42.3.1. Customizing Jolokia
42.3.2. Disabling Jolokia
43. Monitoring and management using a remote shell
43.1. Connecting to the remote shell
43.1.1. Remote shell credentials
43.2. Extending the remote shell
43.2.1. Remote shell commands
43.2.2. Remote shell plugins
44. Metrics
44.1. System metrics
44.2. DataSource metrics
44.3. Tomcat session metrics
44.4. Recording your own metrics
44.5. Adding your own public metrics
44.6. Metric repositories
44.7. Dropwizard Metrics
44.8. Message channel integration
45. Auditing
46. Tracing
46.1. Custom tracing
47. Process monitoring
47.1. Extend configuration
47.2. Programmatically
48. What to read next
VI. Deploying to the cloud
49. Cloud Foundry
49.1. Binding to services
50. Heroku
51. Openshift
52. Google App Engine
53. What to read next
VII. Spring Boot CLI
54. Installing the CLI
55. Using the CLI
55.1. Running applications using the CLI
55.1.1. Deduced “grab” dependencies
55.1.2. Deduced “grab” coordinates
55.1.3. Default import statements
55.1.4. Automatic main method
55.1.5. Custom “grab” metadata
55.2. Testing your code
55.3. Applications with multiple source files
55.4. Packaging your application
55.5. Initialize a new project
55.6. Using the embedded shell
55.7. Adding extensions to the CLI
56. Developing application with the Groovy beans DSL
57. What to read next
VIII. Build tool plugins
58. Spring Boot Maven plugin
58.1. Including the plugin
58.2. Packaging executable jar and war files
59. Spring Boot Gradle plugin
59.1. Including the plugin
59.2. Declaring dependencies without versions
59.2.1. Custom version management
59.3. Default exclude rules
59.4. Packaging executable jar and war files
59.5. Running a project in-place
59.6. Spring Boot plugin configuration
59.7. Repackage configuration
59.8. Repackage with custom Gradle configuration
59.8.1. Configuration options
59.9. Understanding how the Gradle plugin works
59.10. Publishing artifacts to a Maven repository using Gradle
59.10.1. Configuring Gradle to produce a pom that inherits dependency management
59.10.2. Configuring Gradle to produce a pom that imports dependency management
60. Supporting other build systems
60.1. Repackaging archives
60.2. Nested libraries
60.3. Finding a main class
60.4. Example repackage implementation
61. What to read next
IX. ‘How-to’ guides
62. Spring Boot application
62.1. Troubleshoot auto-configuration
62.2. Customize the Environment or ApplicationContext before it starts
62.3. Build an ApplicationContext hierarchy (adding a parent or root context)
62.4. Create a non-web application
63. Properties & configuration
63.1. Externalize the configuration of SpringApplication
63.2. Change the location of external properties of an application
63.3. Use ‘short’ command line arguments
63.4. Use YAML for external properties
63.5. Set the active Spring profiles
63.6. Change configuration depending on the environment
63.7. Discover built-in options for external properties
64. Embedded servlet containers
64.1. Add a Servlet, Filter or ServletContextListener to an application
64.2. Disable registration of a Servlet or Filter
64.3. Change the HTTP port
64.4. Use a random unassigned HTTP port
64.5. Discover the HTTP port at runtime
64.6. Configure SSL
64.7. Configure Tomcat
64.8. Enable Multiple Connectors with Tomcat
64.9. Use Tomcat behind a front-end proxy server
64.10. Use Jetty instead of Tomcat
64.11. Configure Jetty
64.12. Use Undertow instead of Tomcat
64.13. Configure Undertow
64.14. Enable Multiple Listeners with Undertow
64.15. Use Tomcat 7
64.15.1. Use Tomcat 7 with Maven
64.15.2. Use Tomcat 7 with Gradle
64.16. Use Jetty 8
64.16.1. Use Jetty 8 with Maven
64.16.2. Use Jetty 8 with Gradle
64.17. Create WebSocket endpoints using @ServerEndpoint
64.18. Enable HTTP response compression
64.18.1. Enable Tomcat’s HTTP response compression
64.18.2. Enable HTTP response compression using GzipFilter
65. Spring MVC
65.1. Write a JSON REST service
65.2. Write an XML REST service
65.3. Customize the Jackson ObjectMapper
65.4. Customize the @ResponseBody rendering
65.5. Handling Multipart File Uploads
65.6. Switch off the Spring MVC DispatcherServlet
65.7. Switch off the Default MVC configuration
65.8. Customize ViewResolvers
66. Logging
66.1. Configure Logback for logging
66.2. Configure Log4j for logging
66.2.1. Use YAML or JSON to configure Log4j 2
67. Data Access
67.1. Configure a DataSource
67.2. Configure Two DataSources
67.3. Use Spring Data repositories
67.4. Separate @Entity definitions from Spring configuration
67.5. Configure JPA properties
67.6. Use a custom EntityManagerFactory
67.7. Use Two EntityManagers
67.8. Use a traditional persistence.xml
67.9. Use Spring Data JPA and Mongo repositories
67.10. Expose Spring Data repositories as REST endpoint
68. Database initialization
68.1. Initialize a database using JPA
68.2. Initialize a database using Hibernate
68.3. Initialize a database using Spring JDBC
68.4. Initialize a Spring Batch database
68.5. Use a higher level database migration tool
68.5.1. Execute Flyway database migrations on startup
68.5.2. Execute Liquibase database migrations on startup
69. Batch applications
69.1. Execute Spring Batch jobs on startup
70. Actuator
70.1. Change the HTTP port or address of the actuator endpoints
70.2. Customize the ‘whitelabel’ error page
71. Security
71.1. Switch off the Spring Boot security configuration
71.2. Change the AuthenticationManager and add user accounts
71.3. Enable HTTPS when running behind a proxy server
72. Hot swapping
72.1. Reload static content
72.2. Reload Thymeleaf templates without restarting the container
72.3. Reload FreeMarker templates without restarting the container
72.4. Reload Groovy templates without restarting the container
72.5. Reload Velocity templates without restarting the container
72.6. Reload Java classes without restarting the container
72.6.1. Configuring Spring Loaded for use with Maven
72.6.2. Configuring Spring Loaded for use with Gradle and IntelliJ
73. Build
73.1. Customize dependency versions with Maven
73.2. Create an executable JAR with Maven
73.3. Create an additional executable JAR
73.4. Extract specific libraries when an executable jar runs
73.5. Create a non-executable JAR with exclusions
73.6. Remote debug a Spring Boot application started with Maven
73.7. Remote debug a Spring Boot application started with Gradle
73.8. Build an executable archive with Ant
73.9. How to use Java 6
73.9.1. Embedded servlet container compatibility
73.9.2. JTA API compatibility
74. Traditional deployment
74.1. Create a deployable war file
74.2. Create a deployable war file for older servlet containers
74.3. Convert an existing application to Spring Boot
74.4. Deploying a WAR to Weblogic
74.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. Repeated meta-data items
B.2. Generating your own meta-data using the annotation processor
B.2.1. Nested properties
B.2.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