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.0.M1

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. Developer tools
20.1. Property defaults
20.2. Automatic restart
20.2.1. Excluding resources
20.2.2. Disabling restart
20.2.3. Using a trigger file
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. Using the CommandLineRunner
23.7. Application exit
23.8. 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. Typesafe Configuration Properties
24.7.1. Third-party configuration
24.7.2. Relaxed binding
24.7.3. @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.3. File output
26.4. Log Levels
26.5. Custom log configuration
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. Template engines
27.1.6. Error Handling
Error Handling on WebSphere Application Server
27.1.7. Spring HATEOAS
27.2. JAX-RS and Jersey
27.3. Embedded servlet container support
27.3.1. Servlets and Filters
27.3.2. The EmbeddedWebApplicationContext
27.3.3. Customizing embedded servlet containers
Programmatic customization
Customizing ConfigurableEmbeddedServletContainer directly
27.3.4. 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
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.3. Gemfire
30.4. Solr
30.4.1. Connecting to Solr
30.4.2. Spring Data Solr repositories
30.5. Elasticsearch
30.5.1. Connecting to Elasticsearch
30.5.2. Spring Data Elasticsearch repositories
31. Caching
31.1. Supported cache providers
31.1.1. Generic
31.1.2. EhCache 2.x
31.1.3. Hazelcast
31.1.4. Infinispan
31.1.5. JCache
31.1.6. Redis
31.1.7. Guava
31.1.8. Simple
32. Messaging
32.1. JMS
32.1.1. HornetQ support
32.1.2. ActiveMQ support
32.1.3. Using a JNDI ConnectionFactory
32.1.4. Sending a message
32.1.5. Receiving a message
33. Sending email
34. Distributed Transactions with JTA
34.1. Using an Atomikos transaction manager
34.2. Using a Bitronix transaction manager
34.3. Using a Java EE managed transaction manager
34.4. Mixing XA and non-XA JMS connections
34.5. Supporting an alternative embedded transaction manager
35. Spring Integration
36. Monitoring and management over JMX
37. Testing
37.1. Test scope dependencies
37.2. Testing Spring applications
37.3. Testing Spring Boot applications
37.3.1. Using Spock to test Spring Boot applications
37.4. Test utilities
37.4.1. ConfigFileApplicationContextInitializer
37.4.2. EnvironmentTestUtils
37.4.3. OutputCapture
37.4.4. TestRestTemplate
38. Developing auto-configuration and using conditions
38.1. Understanding auto-configured beans
38.2. Locating auto-configuration candidates
38.3. Condition annotations
38.3.1. Class conditions
38.3.2. Bean conditions
38.3.3. Property conditions
38.3.4. Resource conditions
38.3.5. Web application conditions
38.3.6. SpEL expression conditions
39. WebSockets
40. What to read next
V. Spring Boot Actuator: Production-ready features
41. Enabling production-ready features
42. Endpoints
42.1. Customizing endpoints
42.2. Health information
42.3. Security with HealthIndicators
42.3.1. Auto-configured HealthIndicators
42.3.2. Writing custom HealthIndicators
42.4. Custom application info information
42.4.1. Automatically expand info properties at build time
Automatic property expansion using Maven
Automatic property expansion using Gradle
42.4.2. Git commit information
43. Monitoring and management over HTTP
43.1. Securing sensitive endpoints
43.2. Customizing the management server context path
43.3. Customizing the management server port
43.4. Customizing the management server address
43.5. Disabling HTTP endpoints
43.6. HTTP health endpoint access restrictions
44. Monitoring and management over JMX
44.1. Customizing MBean names
44.2. Disabling JMX endpoints
44.3. Using Jolokia for JMX over HTTP
44.3.1. Customizing Jolokia
44.3.2. Disabling Jolokia
45. Monitoring and management using a remote shell
45.1. Connecting to the remote shell
45.1.1. Remote shell credentials
45.2. Extending the remote shell
45.2.1. Remote shell commands
45.2.2. Remote shell plugins
46. Metrics
46.1. System metrics
46.2. DataSource metrics
46.3. Cache metrics
46.4. Tomcat session metrics
46.5. Recording your own metrics
46.6. Adding your own public metrics
46.7. Special features with Java 8
46.8. Metric writers, exporters and aggregation
46.8.1. Example: Export to Redis
46.8.2. Example: Export to Open TSDB
46.8.3. Example: Export to Statsd
46.8.4. Example: Export to JMX
46.9. Aggregating metrics from multiple sources
46.10. Dropwizard Metrics
46.11. Message channel integration
47. Auditing
48. Tracing
48.1. Custom tracing
49. Process monitoring
49.1. Extend configuration
49.2. Programmatically
50. What to read next
51. Deploying Spring Boot applications
52. Deploying to the cloud
52.1. Cloud Foundry
52.1.1. Binding to services
52.2. Heroku
52.3. Openshift
52.4. Google App Engine
53. Installing Spring Boot applications
53.1. Unix/Linux services
53.1.1. Installation as a init.d service (System V)
53.1.2. Installation as a systemd service
53.1.3. Customizing the startup script
54. What to read next
VI. Spring Boot CLI
55. Installing the CLI
56. Using the CLI
56.1. Running applications using the CLI
56.1.1. Deduced “grab” dependencies
56.1.2. Deduced “grab” coordinates
56.1.3. Default import statements
56.1.4. Automatic main method
56.1.5. Custom dependency management
56.2. Testing your code
56.3. Applications with multiple source files
56.4. Packaging your application
56.5. Initialize a new project
56.6. Using the embedded shell
56.7. Adding extensions to the CLI
57. Developing application with the Groovy beans DSL
58. What to read next
VII. Build tool plugins
59. Spring Boot Maven plugin
59.1. Including the plugin
59.2. Packaging executable jar and war files
60. Spring Boot Gradle plugin
60.1. Including the plugin
60.2. Dependency management
60.3. Packaging executable jar and war files
60.4. Running a project in-place
60.5. Spring Boot plugin configuration
60.6. Repackage configuration
60.7. Repackage with custom Gradle configuration
60.7.1. Configuration options
60.8. Understanding how the Gradle plugin works
60.9. Publishing artifacts to a Maven repository using Gradle
60.9.1. Configuring Gradle to produce a pom that inherits dependency management
60.9.2. Configuring Gradle to produce a pom that imports dependency management
61. Supporting other build systems
61.1. Repackaging archives
61.2. Nested libraries
61.3. Finding a main class
61.4. Example repackage implementation
62. What to read next
VIII. ‘How-to’ guides
63. Spring Boot application
63.1. Troubleshoot auto-configuration
63.2. Customize the Environment or ApplicationContext before it starts
63.3. Build an ApplicationContext hierarchy (adding a parent or root context)
63.4. Create a non-web application
64. Properties & configuration
64.1. Externalize the configuration of SpringApplication
64.2. Change the location of external properties of an application
64.3. Use ‘short’ command line arguments
64.4. Use YAML for external properties
64.5. Set the active Spring profiles
64.6. Change configuration depending on the environment
64.7. Discover built-in options for external properties
65. Embedded servlet containers
65.1. Add a Servlet, Filter or ServletContextListener to an application
65.2. Disable registration of a Servlet or Filter
65.3. Change the HTTP port
65.4. Use a random unassigned HTTP port
65.5. Discover the HTTP port at runtime
65.6. Configure SSL
65.7. Configure Tomcat
65.8. Enable Multiple Connectors with Tomcat
65.9. Use Tomcat behind a front-end proxy server
65.10. Use Jetty instead of Tomcat
65.11. Configure Jetty
65.12. Use Undertow instead of Tomcat
65.13. Configure Undertow
65.14. Enable Multiple Listeners with Undertow
65.15. Use Tomcat 7
65.15.1. Use Tomcat 7 with Maven
65.15.2. Use Tomcat 7 with Gradle
65.16. Use Jetty 8
65.16.1. Use Jetty 8 with Maven
65.16.2. Use Jetty 8 with Gradle
65.17. Create WebSocket endpoints using @ServerEndpoint
65.18. Enable HTTP response compression
65.18.1. Enable Tomcat’s HTTP response compression
65.18.2. Enable HTTP response compression using GzipFilter
66. Spring MVC
66.1. Write a JSON REST service
66.2. Write an XML REST service
66.3. Customize the Jackson ObjectMapper
66.4. Customize the @ResponseBody rendering
66.5. Handling Multipart File Uploads
66.6. Switch off the Spring MVC DispatcherServlet
66.7. Switch off the Default MVC configuration
66.8. Customize ViewResolvers
67. Logging
67.1. Configure Logback for logging
67.2. Configure Log4j for logging
67.2.1. Use YAML or JSON to configure Log4j 2
68. Data Access
68.1. Configure a DataSource
68.2. Configure Two DataSources
68.3. Use Spring Data repositories
68.4. Separate @Entity definitions from Spring configuration
68.5. Configure JPA properties
68.6. Use a custom EntityManagerFactory
68.7. Use Two EntityManagers
68.8. Use a traditional persistence.xml
68.9. Use Spring Data JPA and Mongo repositories
68.10. Expose Spring Data repositories as REST endpoint
69. Database initialization
69.1. Initialize a database using JPA
69.2. Initialize a database using Hibernate
69.3. Initialize a database using Spring JDBC
69.4. Initialize a Spring Batch database
69.5. Use a higher level database migration tool
69.5.1. Execute Flyway database migrations on startup
69.5.2. Execute Liquibase database migrations on startup
70. Batch applications
70.1. Execute Spring Batch jobs on startup
71. Actuator
71.1. Change the HTTP port or address of the actuator endpoints
71.2. Customize the ‘whitelabel’ error page
72. Security
72.1. Switch off the Spring Boot security configuration
72.2. Change the AuthenticationManager and add user accounts
72.3. Enable HTTPS when running behind a proxy server
73. Hot swapping
73.1. Reload static content
73.2. Reload templates without restarting the container
73.2.1. Thymeleaf templates
73.2.2. FreeMarker templates
73.2.3. Groovy templates
73.2.4. Velocity templates
73.3. Fast application restarts
73.4. Reload Java classes without restarting the container
73.4.1. Configuring Spring Loaded for use with Maven
73.4.2. Configuring Spring Loaded for use with Gradle and IntelliJ
74. Build
74.1. Customize dependency versions with Maven
74.2. Create an executable JAR with Maven
74.3. Create an additional executable JAR
74.4. Extract specific libraries when an executable jar runs
74.5. Create a non-executable JAR with exclusions
74.6. Remote debug a Spring Boot application started with Maven
74.7. Remote debug a Spring Boot application started with Gradle
74.8. Build an executable archive with Ant
74.9. How to use Java 6
74.9.1. Embedded servlet container compatibility
74.9.2. JTA API compatibility
75. Traditional deployment
75.1. Create a deployable war file
75.2. Create a deployable war file for older servlet containers
75.3. Convert an existing application to Spring Boot
75.4. Deploying a WAR to Weblogic
75.5. Deploying a WAR in an Old (Servlet 2.5) Container
IX. 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