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

Copyright © 2012-2017

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.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.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.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.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.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. Mocking and spying beans
41.3.5. Auto-configured tests
41.3.6. Auto-configured JSON tests
41.3.7. Auto-configured Spring MVC tests
41.3.8. Auto-configured Data JPA tests
41.3.9. Auto-configured JDBC tests
41.3.10. Auto-configured Data MongoDB tests
41.3.11. Auto-configured REST clients
41.3.12. Auto-configured Spring REST Docs tests
41.3.13. User configuration and slicing
41.3.14. 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

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