Authors

Phillip Webb, Dave Syer, Josh Long, Stéphane Nicoll, Rob Winch, Andy Wilkinson, Marcel Overdijk, Christian Dupuis, Sébastien Deleuze

1.4.1.BUILD-SNAPSHOT

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. 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. ConfigurableWebBindingInitializer
      • 27.1.7. Template engines
      • 27.1.8. Error Handling
      • • Custom error pages
        • Mapping error pages outside of Spring MVC
        • Error Handling on WebSphere Application Server
      • 27.1.9. Spring HATEOAS
      • 27.1.10. 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
    • 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
  • 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
      • 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. HornetQ support
      • 32.1.4. Using a JNDI ConnectionFactory
      • 32.1.5. Sending a message
      • 32.1.6. Receiving a message
    • 32.2. AMQP
    • • 32.2.1. RabbitMQ support
      • 32.2.2. Sending a message
      • 32.2.3. Receiving a message
  • 33. Calling REST services
  • • 33.1. RestTemplate customization
  • 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 Narayana transaction manager
    • 35.4. Using a Java EE managed transaction manager
    • 35.5. Mixing XA and non-XA JMS connections
    • 35.6. 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. Detecting test configuration
      • 40.3.2. Excluding test configuration
      • 40.3.3. Working with random ports
      • 40.3.4. Mocking and spying beans
      • 40.3.5. Auto-configured tests
      • 40.3.6. Auto-configured JSON tests
      • 40.3.7. Auto-configured Spring MVC tests
      • 40.3.8. Auto-configured Data JPA tests
      • 40.3.9. Auto-configured REST clients
      • 40.3.10. Auto-configured Spring REST Docs tests
      • 40.3.11. 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. WebSockets
  • 42. Web Services
  • 43. Creating your own auto-configuration
  • • 43.1. Understanding auto-configured beans
    • 43.2. Locating auto-configuration candidates
    • 43.3. Condition annotations
    • • 43.3.1. Class conditions
      • 43.3.2. Bean conditions
      • 43.3.3. Property conditions
      • 43.3.4. Resource conditions
      • 43.3.5. Web application conditions
      • 43.3.6. SpEL expression conditions
    • 43.4. Creating your own starter
    • • 43.4.1. Naming
      • 43.4.2. Autoconfigure module
      • 43.4.3. Starter module
  • 44. What to read next
• V. Spring Boot Actuator: Production-ready features
• • 45. Enabling production-ready features
  • 46. Endpoints
  • • 46.1. Customizing endpoints
    • 46.2. Hypermedia for actuator MVC endpoints
    • 46.3. CORS support
    • 46.4. Adding custom endpoints
    • 46.5. Health information
    • 46.6. Security with HealthIndicators
    • • 46.6.1. Auto-configured HealthIndicators
      • 46.6.2. Writing custom HealthIndicators
    • 46.7. Application information
    • • 46.7.1. Auto-configured InfoContributors
      • 46.7.2. Custom application info information
      • 46.7.3. Git commit information
      • 46.7.4. Build information
      • 46.7.5. Writing custom InfoContributors
  • 47. Monitoring and management over HTTP
  • • 47.1. Securing sensitive endpoints
    • 47.2. Customizing the management endpoint paths
    • 47.3. Customizing the management server port
    • 47.4. Configuring management-specific SSL
    • 47.5. Customizing the management server address
    • 47.6. Disabling HTTP endpoints
    • 47.7. HTTP health endpoint access restrictions
  • 48. Monitoring and management over JMX
  • • 48.1. Customizing MBean names
    • 48.2. Disabling JMX endpoints
    • 48.3. Using Jolokia for JMX over HTTP
    • • 48.3.1. Customizing Jolokia
      • 48.3.2. Disabling Jolokia
  • 49. Monitoring and management using a remote shell
  • • 49.1. Connecting to the remote shell
    • • 49.1.1. Remote shell credentials
    • 49.2. Extending the remote shell
    • • 49.2.1. Remote shell commands
      • 49.2.2. Remote shell plugins
  • 50. Metrics
  • • 50.1. System metrics
    • 50.2. DataSource metrics
    • 50.3. Cache metrics
    • 50.4. Tomcat session metrics
    • 50.5. Recording your own metrics
    • 50.6. Adding your own public metrics
    • 50.7. Special features with Java 8
    • 50.8. Metric writers, exporters and aggregation
    • • 50.8.1. Example: Export to Redis
      • 50.8.2. Example: Export to Open TSDB
      • 50.8.3. Example: Export to Statsd
      • 50.8.4. Example: Export to JMX
    • 50.9. Aggregating metrics from multiple sources
    • 50.10. Dropwizard Metrics
    • 50.11. Message channel integration
  • 51. Auditing
  • 52. Tracing
  • • 52.1. Custom tracing
  • 53. Process monitoring
  • • 53.1. Extend configuration
    • 53.2. Programmatically
  • 54. What to read next
• VI. Deploying Spring Boot applications
• • 55. Deploying to the cloud
  • • 55.1. Cloud Foundry
    • • 55.1.1. Binding to services
    • 55.2. Heroku
    • 55.3. OpenShift
    • 55.4. Boxfuse and Amazon Web Services
    • 55.5. Google App Engine
  • 56. Installing Spring Boot applications
  • • 56.1. Unix/Linux services
    • • 56.1.1. Installation as an init.d service (System V)
      • • Securing an init.d service
      • 56.1.2. Installation as a systemd service
      • 56.1.3. Customizing the startup script
      • • Customizing script when it’s written
        • Customizing script when it runs
    • 56.2. 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.7.2. Available layouts
    • 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. Create your own FailureAnalyzer
    • 68.2. Troubleshoot auto-configuration
    • 68.3. Customize the Environment or ApplicationContext before it starts
    • 68.4. Build an ApplicationContext hierarchy (adding a parent or root context)
    • 68.5. Create a non-web application
  • 69. Properties & configuration
  • • 69.1. Automatically expand properties at build time
    • • 69.1.1. Automatic property expansion using Maven
      • 69.1.2. Automatic property expansion using Gradle
    • 69.2. Externalize the configuration of SpringApplication
    • 69.3. Change the location of external properties of an application
    • 69.4. Use ‘short’ command line arguments
    • 69.5. Use YAML for external properties
    • 69.6. Set the active Spring profiles
    • 69.7. Change configuration depending on the environment
    • 69.8. 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. Configure Access Logging
    • 70.7. Use behind a front-end proxy server
    • • 70.7.1. Customize Tomcat’s proxy configuration
    • 70.8. Configure Tomcat
    • 70.9. Enable Multiple Connectors with Tomcat
    • 70.10. Use Tomcat’s LegacyCookieProcessor
    • 70.11. Use Jetty instead of Tomcat
    • 70.12. Configure Jetty
    • 70.13. Use Undertow instead of Tomcat
    • 70.14. Configure Undertow
    • 70.15. Enable Multiple Listeners with Undertow
    • 70.16. Use Tomcat 7.x or 8.0
    • • 70.16.1. Use Tomcat 7.x or 8.0 with Maven
      • 70.16.2. Use Tomcat 7.x or 8.0 with Gradle
    • 70.17. Use Jetty 9.2
    • • 70.17.1. Use Jetty 9.2 with Maven
      • 70.17.2. Use Jetty 9.2 with Gradle
    • 70.18. Use Jetty 8
    • • 70.18.1. Use Jetty 8 with Maven
      • 70.18.2. Use Jetty 8 with Gradle
    • 70.19. Create WebSocket endpoints using @ServerEndpoint
    • 70.20. 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
    • 71.10. Use Thymeleaf 3
  • 72. HTTP clients
  • • 72.1. Configure RestTemplate to use a proxy
  • 73. Logging
  • • 73.1. Configure Logback for logging
    • • 73.1.1. Configure logback for file only output
    • 73.2. Configure Log4j for logging
    • • 73.2.1. Use YAML or JSON to configure Log4j 2
  • 74. Data Access
  • • 74.1. Configure a DataSource
    • 74.2. Configure Two DataSources
    • 74.3. Use Spring Data repositories
    • 74.4. Separate @Entity definitions from Spring configuration
    • 74.5. Configure JPA properties
    • 74.6. Use a custom EntityManagerFactory
    • 74.7. Use Two EntityManagers
    • 74.8. Use a traditional persistence.xml
    • 74.9. Use Spring Data JPA and Mongo repositories
    • 74.10. Expose Spring Data repositories as REST endpoint
    • 74.11. Configure a component that is used by JPA
  • 75. Database initialization
  • • 75.1. Initialize a database using JPA
    • 75.2. Initialize a database using Hibernate
    • 75.3. Initialize a database using Spring JDBC
    • 75.4. Initialize a Spring Batch database
    • 75.5. Use a higher-level database migration tool
    • • 75.5.1. Execute Flyway database migrations on startup
      • 75.5.2. Execute Liquibase database migrations on startup
  • 76. Batch applications
  • • 76.1. Execute Spring Batch jobs on startup
  • 77. Actuator
  • • 77.1. Change the HTTP port or address of the actuator endpoints
    • 77.2. Customize the ‘whitelabel’ error page
    • 77.3. Actuator and Jersey
  • 78. Security
  • • 78.1. Switch off the Spring Boot security configuration
    • 78.2. Change the AuthenticationManager and add user accounts
    • 78.3. Enable HTTPS when running behind a proxy server
  • 79. Hot swapping
  • • 79.1. Reload static content
    • 79.2. Reload templates without restarting the container
    • • 79.2.1. Thymeleaf templates
      • 79.2.2. FreeMarker templates
      • 79.2.3. Groovy templates
      • 79.2.4. Velocity templates
    • 79.3. Fast application restarts
    • 79.4. Reload Java classes without restarting the container
    • • 79.4.1. Configuring Spring Loaded for use with Maven
      • 79.4.2. Configuring Spring Loaded for use with Gradle and IntelliJ IDEA
  • 80. Build
  • • 80.1. Generate build information
    • 80.2. Generate git information
    • 80.3. Customize dependency versions
    • 80.4. Create an executable JAR with Maven
    • 80.5. Use a Spring Boot application as a dependency
    • 80.6. Extract specific libraries when an executable jar runs
    • 80.7. Create a non-executable JAR with exclusions
    • 80.8. Remote debug a Spring Boot application started with Maven
    • 80.9. Remote debug a Spring Boot application started with Gradle
    • 80.10. Build an executable archive from Ant without using spring-boot-antlib
    • 80.11. How to use Java 6
    • • 80.11.1. Embedded servlet container compatibility
      • 80.11.2. Jackson
      • 80.11.3. JTA API compatibility
  • 81. Traditional deployment
  • • 81.1. Create a deployable war file
    • 81.2. Create a deployable war file for older servlet containers
    • 81.3. Convert an existing application to Spring Boot
    • 81.4. Deploying a WAR to WebLogic
    • 81.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