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

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. 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. 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
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. 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. 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.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
32. Caching
32.1. Supported cache providers
32.1.1. Generic
32.1.2. EhCache 2.x
32.1.3. Hazelcast
32.1.4. Infinispan
32.1.5. JCache
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. Spring Integration
37. Spring Session
38. Monitoring and management over JMX
39. Testing
39.1. Test scope dependencies
39.2. Testing Spring applications
39.3. Testing Spring Boot applications
39.3.1. Using Spock to test Spring Boot applications
39.4. Test utilities
39.4.1. ConfigFileApplicationContextInitializer
39.4.2. EnvironmentTestUtils
39.4.3. OutputCapture
39.4.4. TestRestTemplate
40. Developing auto-configuration and using conditions
40.1. Understanding auto-configured beans
40.2. Locating auto-configuration candidates
40.3. Condition annotations
40.3.1. Class conditions
40.3.2. Bean conditions
40.3.3. Property conditions
40.3.4. Resource conditions
40.3.5. Web application conditions
40.3.6. SpEL expression conditions
41. WebSockets
42. What to read next
V. Spring Boot Actuator: Production-ready features
43. Enabling production-ready features
44. Endpoints
44.1. Customizing endpoints
44.2. Hypermedia for actuator MVC endpoints
44.3. Adding custom endpoints
44.4. Health information
44.5. Security with HealthIndicators
44.5.1. Auto-configured HealthIndicators
44.5.2. Writing custom HealthIndicators
44.6. Custom application info information
44.6.1. Automatically expand info properties at build time
Automatic property expansion using Maven
Automatic property expansion using Gradle
44.6.2. Git commit information
45. Monitoring and management over HTTP
45.1. Securing sensitive endpoints
45.2. Customizing the management server context path
45.3. Customizing the management server port
45.4. Customizing the management server address
45.5. Disabling HTTP endpoints
45.6. HTTP health endpoint access restrictions
46. Monitoring and management over JMX
46.1. Customizing MBean names
46.2. Disabling JMX endpoints
46.3. Using Jolokia for JMX over HTTP
46.3.1. Customizing Jolokia
46.3.2. Disabling Jolokia
47. Monitoring and management using a remote shell
47.1. Connecting to the remote shell
47.1.1. Remote shell credentials
47.2. Extending the remote shell
47.2.1. Remote shell commands
47.2.2. Remote shell plugins
48. Metrics
48.1. System metrics
48.2. DataSource metrics
48.3. Cache metrics
48.4. Tomcat session metrics
48.5. Recording your own metrics
48.6. Adding your own public metrics
48.7. Special features with Java 8
48.8. Metric writers, exporters and aggregation
48.8.1. Example: Export to Redis
48.8.2. Example: Export to Open TSDB
48.8.3. Example: Export to Statsd
48.8.4. Example: Export to JMX
48.9. Aggregating metrics from multiple sources
48.10. Dropwizard Metrics
48.11. Message channel integration
49. Auditing
50. Tracing
50.1. Custom tracing
51. Process monitoring
51.1. Extend configuration
51.2. Programmatically
52. What to read next
VI. Deploying Spring Boot applications
53. Deploying to the cloud
53.1. Cloud Foundry
53.1.1. Binding to services
53.2. Heroku
53.3. Openshift
53.4. Google App Engine
54. Installing Spring Boot applications
54.1. Unix/Linux services
54.1.1. Installation as a init.d service (System V)
54.1.2. Installation as a systemd service
54.1.3. Customizing the startup script
55. What to read next
VII. Spring Boot CLI
56. Installing the CLI
57. Using the CLI
57.1. Running applications using the CLI
57.1.1. Deduced “grab” dependencies
57.1.2. Deduced “grab” coordinates
57.1.3. Default import statements
57.1.4. Automatic main method
57.1.5. Custom dependency management
57.2. Testing your code
57.3. Applications with multiple source files
57.4. Packaging your application
57.5. Initialize a new project
57.6. Using the embedded shell
57.7. Adding extensions to the CLI
58. Developing application with the Groovy beans DSL
59. What to read next
VIII. Build tool plugins
60. Spring Boot Maven plugin
60.1. Including the plugin
60.2. Packaging executable jar and war files
61. Spring Boot Gradle plugin
61.1. Including the plugin
61.2. Dependency management
61.3. Packaging executable jar and war files
61.4. Running a project in-place
61.5. Spring Boot plugin configuration
61.6. Repackage configuration
61.7. Repackage with custom Gradle configuration
61.7.1. Configuration options
61.8. Understanding how the Gradle plugin works
61.9. Publishing artifacts to a Maven repository using Gradle
61.9.1. Configuring Gradle to produce a pom that inherits dependency management
61.9.2. Configuring Gradle to produce a pom that imports dependency management
62. Spring Boot AntLib module
62.1. Spring Boot Ant tasks
62.1.1. spring-boot:exejar
Examples
62.2. spring-boot:findmainclass
62.2.1. Examples
63. Supporting other build systems
63.1. Repackaging archives
63.2. Nested libraries
63.3. Finding a main class
63.4. Example repackage implementation
64. What to read next
IX. ‘How-to’ guides
65. Spring Boot application
65.1. Troubleshoot auto-configuration
65.2. Customize the Environment or ApplicationContext before it starts
65.3. Build an ApplicationContext hierarchy (adding a parent or root context)
65.4. Create a non-web application
66. Properties & configuration
66.1. Externalize the configuration of SpringApplication
66.2. Change the location of external properties of an application
66.3. Use ‘short’ command line arguments
66.4. Use YAML for external properties
66.5. Set the active Spring profiles
66.6. Change configuration depending on the environment
66.7. Discover built-in options for external properties
67. Embedded servlet containers
67.1. Add a Servlet, Filter or ServletContextListener to an application
67.2. Disable registration of a Servlet or Filter
67.3. Change the HTTP port
67.4. Use a random unassigned HTTP port
67.5. Discover the HTTP port at runtime
67.6. Configure SSL
67.7. Configure Tomcat
67.8. Enable Multiple Connectors with Tomcat
67.9. Use Tomcat behind a front-end proxy server
67.10. Use Jetty instead of Tomcat
67.11. Configure Jetty
67.12. Use Undertow instead of Tomcat
67.13. Configure Undertow
67.14. Enable Multiple Listeners with Undertow
67.15. Use Tomcat 7
67.15.1. Use Tomcat 7 with Maven
67.15.2. Use Tomcat 7 with Gradle
67.16. Use Jetty 8
67.16.1. Use Jetty 8 with Maven
67.16.2. Use Jetty 8 with Gradle
67.17. Create WebSocket endpoints using @ServerEndpoint
67.18. Enable HTTP response compression
68. Spring MVC
68.1. Write a JSON REST service
68.2. Write an XML REST service
68.3. Customize the Jackson ObjectMapper
68.4. Customize the @ResponseBody rendering
68.5. Handling Multipart File Uploads
68.6. Switch off the Spring MVC DispatcherServlet
68.7. Switch off the Default MVC configuration
68.8. Customize ViewResolvers
69. Logging
69.1. Configure Logback for logging
69.2. Configure Log4j for logging
69.2.1. Use YAML or JSON to configure Log4j 2
70. Data Access
70.1. Configure a DataSource
70.2. Configure Two DataSources
70.3. Use Spring Data repositories
70.4. Separate @Entity definitions from Spring configuration
70.5. Configure JPA properties
70.6. Use a custom EntityManagerFactory
70.7. Use Two EntityManagers
70.8. Use a traditional persistence.xml
70.9. Use Spring Data JPA and Mongo repositories
70.10. Expose Spring Data repositories as REST endpoint
71. Database initialization
71.1. Initialize a database using JPA
71.2. Initialize a database using Hibernate
71.3. Initialize a database using Spring JDBC
71.4. Initialize a Spring Batch database
71.5. Use a higher level database migration tool
71.5.1. Execute Flyway database migrations on startup
71.5.2. Execute Liquibase database migrations on startup
72. Batch applications
72.1. Execute Spring Batch jobs on startup
73. Actuator
73.1. Change the HTTP port or address of the actuator endpoints
73.2. Customize the ‘whitelabel’ error page
74. Security
74.1. Switch off the Spring Boot security configuration
74.2. Change the AuthenticationManager and add user accounts
74.3. Enable HTTPS when running behind a proxy server
75. Hot swapping
75.1. Reload static content
75.2. Reload templates without restarting the container
75.2.1. Thymeleaf templates
75.2.2. FreeMarker templates
75.2.3. Groovy templates
75.2.4. Velocity templates
75.3. Fast application restarts
75.4. Reload Java classes without restarting the container
75.4.1. Configuring Spring Loaded for use with Maven
75.4.2. Configuring Spring Loaded for use with Gradle and IntelliJ IDEA
76. Build
76.1. Customize dependency versions with Maven
76.2. Create an executable JAR with Maven
76.3. Create an additional executable JAR
76.4. Extract specific libraries when an executable jar runs
76.5. Create a non-executable JAR with exclusions
76.6. Remote debug a Spring Boot application started with Maven
76.7. Remote debug a Spring Boot application started with Gradle
76.8. Build an executable archive from Ant without using spring-boot-antlib
76.9. How to use Java 6
76.9.1. Embedded servlet container compatibility
76.9.2. JTA API compatibility
77. Traditional deployment
77.1. Create a deployable war file
77.2. Create a deployable war file for older servlet containers
77.3. Convert an existing application to Spring Boot
77.4. Deploying a WAR to Weblogic
77.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 hints
B.2.2. Provider hints
Any
Class reference
Enum
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