[[howto]]
= ``How-to'' guides

[partintro]
--
This section provides answers to some common '``how do I do that...''' type of questions
that often arise when using Spring Boot. This is by no means an exhaustive list, but it
does cover quite a lot.

If you are having a specific problem that we don't cover here, you might want to check out
http://stackoverflow.com/tags/spring-boot[stackoverflow.com] to see if someone has
already provided an answer; this is also a great place to ask new questions (please use
the `spring-boot` tag).

We're also more than happy to extend this section; If you want to add a ``how-to'' you
can send us a {github-code}[pull request].
--



[[howto-spring-boot-application]]
== Spring Boot application



[[howto-troubleshoot-auto-configuration]]
=== Troubleshoot auto-configuration
The Spring Boot auto-configuration tries its best to ``do the right thing'', but
sometimes things fail and it can be hard to tell why.

There is a really useful `AutoConfigurationReport` available in any Spring Boot
`ApplicationContext`. You will see it if you enable `DEBUG` logging output. If you use
the `spring-boot-actuator` there is also an `autoconfig` endpoint that renders the report
in JSON. Use that to debug the application and see what features have been added (and
which not) by Spring Boot at runtime.

Many more questions can be answered by looking at the source code and the javadoc. Some
rules of thumb:

* Look for classes called `*AutoConfiguration` and read their sources, in particular the
  `@Conditional*` annotations to find out what features they enable and when. Add
  `--debug` to the command line or a System property `-Ddebug` to get a log on the
  console of all the autoconfiguration decisions that were made in your app. In a running
  Actuator app look at the `autoconfig` endpoint (`/autoconfig' or the JMX equivalent) for
  the same information.
* Look for classes that are `@ConfigurationProperties` (e.g.
  {sc-spring-boot-autoconfigure}/web/ServerProperties.{sc-ext}[`ServerProperties`])
  and read from there the available external configuration options. The
  `@ConfigurationProperties` has a `name` attribute which acts as a prefix to external
  properties, thus `ServerProperties` has `prefix="server"` and its configuration properties
  are `server.port`, `server.address` etc. In a running Actuator app look at the
  `configprops` endpoint.
* Look for use of `RelaxedEnvironment` to pull configuration values explicitly out of the
  `Environment`. It often is used with a prefix.
* Look for `@Value` annotations that bind directly to the `Environment`. This is less
  flexible than the `RelaxedEnvironment` approach, but does allow some relaxed binding,
  specifically for OS environment variables (so `CAPITALS_AND_UNDERSCORES` are synonyms
  for `period.separated`).
* Look for `@ConditionalOnExpression` annotations that switch features on and off in
  response to SpEL expressions, normally evaluated with place-holders resolved from the
  `Environment`.



[[howto-customize-the-environment-or-application-context]]
=== Customize the Environment or ApplicationContext before it starts
A `SpringApplication` has `ApplicationListeners` and `ApplicationContextInitializers` that
are used to apply customizations to the context or environment. Spring Boot loads a number
of such customizations for use internally from `META-INF/spring.factories`. There is more
than one way to register additional ones:

* Programmatically per application by calling the `addListeners` and `addInitializers`
  methods on `SpringApplication` before you run it.
* Declaratively per application by setting `context.initializer.classes` or
  `context.listener.classes`.
* Declaratively for all applications by adding a `META-INF/spring.factories` and packaging
  a jar file that the applications all use as a library.

The `SpringApplication` sends some special `ApplicationEvents` to the listeners (even
some before the context is created), and then registers the listeners for events published
by the `ApplicationContext` as well. See
'<<spring-boot-features.adoc#boot-features-application-events-and-listeners>>' in the
``Spring Boot features'' section for a complete list.



[[howto-build-an-application-context-hierarchy]]
=== Build an ApplicationContext hierarchy (adding a parent or root context)
You can use the `ApplicationBuilder` class to create parent/child `ApplicationContext`
hierarchies. See '<<spring-boot-features.adoc#boot-features-fluent-builder-api>>'
in the ``Spring Boot features'' section for more information.



[[howto-create-a-non-web-application]]
=== Create a non-web application
Not all Spring applications have to be web applications (or web services). If you want to
execute some code in a `main` method, but also bootstrap a Spring application to set up
the infrastructure to use, then it's easy with the `SpringApplication` features of Spring
Boot. A `SpringApplication` changes its `ApplicationContext` class depending on whether it
thinks it needs a web application or not. The first thing you can do to help it is to just
leave the servlet API dependencies off the classpath. If you can't do that (e.g. you are
running 2 applications from the same code base) then you can explicitly call
`SpringApplication.setWebEnvironment(false)`, or set the `applicationContextClass`
property (through the Java API or with external properties).
Application code that you want to run as your business logic can be implemented as a
`CommandLineRunner` and dropped into the context as a `@Bean` definition.



[[howto-properties-and-configuration]]
== Properties & configuration



[[howto-externalize-configuration]]
=== Externalize the configuration of SpringApplication
A `SpringApplication` has bean properties (mainly setters) so you can use its Java API as
you create the application to modify its behavior. Or you can externalize the
configuration using properties in `spring.main.*`. E.g. in `application.properties` you
might have.

[source,properties,indent=0,subs="verbatim,quotes,attributes"]
----
	spring.main.web_environment=false
	spring.main.show_banner=false
----

and then the Spring Boot banner will not be printed on startup, and the application will
not be a web application.

NOTE: The example above also demonstrates how flexible binding allows the use of
underscores (`_`) as well as dashes (`-`) in property names.

[[howto-change-the-location-of-external-properties]]
=== Change the location of external properties of an application
By default properties from different sources are added to the Spring `Environment` in a
defined order (see '<<spring-boot-features.adoc#boot-features-external-config>>' in
the ``Spring Boot features'' section for the exact order).

A nice way to augment and modify this is to add `@PropertySource` annotations to your
application sources. Classes passed to the `SpringApplication` static convenience
methods, and those added using `setSources()` are inspected to see if they have
`@PropertySources`, and if they do, those properties are added to the `Environment` early
enough to be used in all phases of the `ApplicationContext` lifecycle. Properties added
in this way have precedence over any added using the default locations, but have lower
priority than system properties, environment variables or the command line.

You can also provide System properties (or environment variables) to change the behavior:

* `spring.config.name` (`SPRING_CONFIG_NAME`), defaults to `application` as the root of
  the file name.
* `spring.config.location` (`SPRING_CONFIG_LOCATION`) is the file to load (e.g. a classpath
  resource or a URL). A separate `Environment` property source is set up for this document
  and it can be overridden by system properties, environment variables or the
  command line.

No matter what you set in the environment, Spring Boot will always load
`application.properties` as described above. If YAML is used then files with the ``.yml''
extension are also added to the list by default.

See {sc-spring-boot}/context/config/ConfigFileApplicationListener.{sc-ext}[`ConfigFileApplicationListener`]
for more detail.



[[howto-use-short-command-line-arguments]]
=== Use ``short'' command line arguments
Some people like to use (for example) `--port=9000` instead of `--server.port=9000` to
set configuration properties on the command line. You can easily enable this by using
placeholders in `application.properties`, e.g.

[source,properties,indent=0,subs="verbatim,quotes,attributes"]
----
	server.port=${port:8080}
----

TIP: If you have enabled maven filtering for the `application.properties` you may want
to avoid using `${*}` for the tokens to filter as it conflicts with those placeholders.
You can either use `@*@` (i.e. `@maven.token@` instead of `${maven.token}`) or you can
configure the `maven-resources-plugin` to use
http://maven.apache.org/plugins/maven-resources-plugin/resources-mojo.html#delimiters[other delimiters].

NOTE: In this specific case the port binding will work in a PaaS environment like Heroku
and Cloud Foundry, since in those two platforms the `PORT` environment variable is set
automatically and Spring can bind to capitalized synonyms for `Environment` properties.



[[howto-use-yaml-for-external-properties]]
=== Use YAML for external properties
YAML is a superset of JSON and as such is a very convenient syntax for storing external
properties in a hierarchical format. E.g.

[source,yaml,indent=0,subs="verbatim,quotes,attributes"]
----
	spring:
		application:
			name: cruncher
		datasource:
			driverClassName: com.mysql.jdbc.Driver
			url: jdbc:mysql://localhost/test
	server:
		port: 9000
----

Create a file called `application.yml` and stick it in the root of your classpath, and
also add `snakeyaml` to your dependencies (Maven coordinates `org.yaml:snakeyaml`, already
included if you use the `spring-boot-starter`). A YAML file is parsed to a Java
`Map<String,Object>` (like a JSON object), and Spring Boot flattens the map so that it
is 1-level deep and has period-separated keys, a lot like people are used to with
`Properties` files in Java.

The example YAML above corresponds to an `application.properties` file

[source,properties,indent=0,subs="verbatim,quotes,attributes"]
----
	spring.application.name=cruncher
	spring.datasource.driverClassName=com.mysql.jdbc.Driver
	spring.datasource.url=jdbc:mysql://localhost/test
	server.port=9000
----

See '<<spring-boot-features.adoc#boot-features-external-config-yaml>>' in
the ``Spring Boot features'' section for more information
about YAML.

[[howto-set-active-spring-profiles]]
=== Set the active Spring profiles
The Spring `Environment` has an API for this, but normally you would set a System profile
(`spring.profiles.active`) or an OS environment variable (`SPRING_PROFILES_ACTIVE`). E.g.
launch your application with a `-D` argument (remember to put it before the main class
or jar archive):

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ java -jar -Dspring.profiles.active=production demo-0.0.1-SNAPSHOT.jar
----

In Spring Boot you can also set the active profile in `application.properties`, e.g.

[source,properties,indent=0,subs="verbatim,quotes,attributes"]
----
	spring.profiles.active=production
----

A value set this way is replaced by the System property or environment variable setting,
but not by the `SpringApplicationBuilder.profiles()` method. Thus the latter Java API can
be used to augment the profiles without changing the defaults.

See '<<spring-boot-features.adoc#boot-features-profiles>>' in
the ``Spring Boot features'' section for more information.



[[howto-change-configuration-depending-on-the-environment]]
=== Change configuration depending on the environment
A YAML file is actually a sequence of documents separated by `---` lines, and each
document is parsed separately to a flattened map.

If a YAML document contains a `spring.profiles` key, then the profiles value
(comma-separated list of profiles) is fed into the Spring
`Environment.acceptsProfiles()` and if any of those profiles is active that document is
included in the final merge (otherwise not).

Example:

[source,yaml,indent=0,subs="verbatim,quotes,attributes"]
----
	server:
		port: 9000
	---

	spring:
		profiles: development
	server:
		port: 9001

	---

	spring:
		profiles: production
	server:
		port: 0
----

In this example the default port is 9000, but if the Spring profile ``development'' is
active then the port is 9001, and if ``production'' is active then it is 0.

The YAML documents are merged in the order they are encountered (so later values override
earlier ones).

To do the same thing with properties files you can use `application-${profile}.properties`
to specify profile-specific values.



[[howto-discover-build-in-options-for-external-properties]]
=== Discover built-in options for external properties
Spring Boot binds external properties from `application.properties` (or `.yml`) (and
other places) into an application at runtime. There is not (and technically cannot be)
an exhaustive list of all supported properties in a single location because contributions
can come from additional jar files on your classpath.

A running application with the Actuator features has a `configprops` endpoint that shows
all the bound and bindable properties available through `@ConfigurationProperties`.

The appendix includes an <<appendix-application-properties#common-application-properties,
`application.properties`>> example with a list of the most common properties supported by
Spring Boot. The definitive list comes from searching the source code for
`@ConfigurationProperties` and `@Value` annotations, as well as the occasional use of
`RelaxedEnvironment`.



[[howto-embedded-servlet-containers]]
== Embedded servlet containers



[[howto-add-a-servlet-filter-or-servletcontextlistener]]
=== Add a Servlet, Filter or ServletContextListener to an application
`Servlet`, `Filter`, `ServletContextListener` and the other listeners supported by the
Servlet spec can be added to your application as `@Bean` definitions. Be very careful that
they don't cause eager initialization of too many other beans because they have to be
installed in the container very early in the application lifecycle (e.g. it's not a good
idea to have them depend on your `DataSource` or JPA configuration). You can work around
restrictions like that by initializing them lazily when first used instead of on
initialization.

In the case of `Filters` and `Servlets` you can also add mappings and init parameters by
adding a `FilterRegistrationBean` or `ServletRegistrationBean` instead of or as well as
the underlying component.



[[howto-change-the-http-port]]
=== Change the HTTP port
In a standalone application the main HTTP port defaults to `8080`, but can be set with
`server.port` (e.g. in `application.properties` or as a System property). Thanks to
relaxed binding of `Environment` values you can also use `SERVER_PORT` (e.g. as an OS
environment variable).

To switch off the HTTP endpoints completely, but still create a `WebApplicationContext`,
use `server.port=-1` (this is sometimes useful for testing).

For more details look at '<<spring-boot-features.adoc#boot-features-customizing-embedded-containers>>'
in the ``Spring Boot features'' section, or the
{sc-spring-boot-autoconfigure}/web/ServerProperties.{sc-ext}[`ServerProperties`] source
code.


[[howto-user-a-random-unassigned-http-port]]
=== Use a random unassigned HTTP port
To scan for a free port (using OS natives to prevent clashes) use `server.port=0`.



[[howto-discover-the-http-port-at-runtime]]
=== Discover the HTTP port at runtime
You can access the port the server is running on from log output or from the
`EmbeddedWebApplicationContext` via its `EmbeddedServletContainer`. The best way to get
that and be sure that it has initialized is to add a `@Bean` of type
`ApplicationListener<EmbeddedServletContainerInitializedEvent>` and pull the container
out of the event when it is published.

A really useful thing to do in is to use `@IntegrationTest` to set `server.port=0`
and then inject the actual (``local'') port as a `@Value`. For example:

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@RunWith(SpringJUnit4ClassRunner.class)
	@SpringApplicationConfiguration(classes = SampleDataJpaApplication.class)
	@WebAppConfiguration
	@IntegrationTest("server.port:0")
	public class CityRepositoryIntegrationTests {

		@Autowired
		EmbeddedWebApplicationContext server;

		@Value("${local.server.port}")
		int port;

		// ...

	}
----



[[howto-configure-tomcat]]
=== Configure Tomcat
Generally you can follow the advice from
'<<howto-discover-build-in-options-for-external-properties>>' about
`@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at
`EmbeddedServletContainerCustomizer` and various Tomcat specific `*Customizers` that you
can add in one of those. The Tomcat APIs are quite rich so once you have access to the
`TomcatEmbeddedServletContainerFactory` you can modify it in a number of ways. Or the
nuclear option is to add your own `TomcatEmbeddedServletContainerFactory`.



[[howto-terminate-ssl-in-tomcat]]
=== Terminate SSL in Tomcat
Use an `EmbeddedServletContainerCustomizer` and in that add a `TomcatConnectorCustomizer`
that sets up the connector to be secure:

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@Bean
	public EmbeddedServletContainerCustomizer containerCustomizer(){
		return new MyCustomizer();
	}

	// ...

	private static class MyCustomizer implements EmbeddedServletContainerCustomizer {

		@Override
		public void customize(ConfigurableEmbeddedServletContainer factory) {
			if(factory instanceof TomcatEmbeddedServletContainerFactory) {
				customizeTomcat((TomcatEmbeddedServletContainerFactory) factory));
			}
		}

		public void customizeTomcat(TomcatEmbeddedServletContainerFactory factory) {
			factory.addConnectorCustomizers(new TomcatConnectorCustomizer() {
				@Override
				public void customize(Connector connector) {
					connector.setPort(serverPort);
					connector.setSecure(true);
					connector.setScheme("https");
					connector.setAttribute("keyAlias", "tomcat");
					connector.setAttribute("keystorePass", "password");
					try {
						connector.setAttribute("keystoreFile",
							ResourceUtils.getFile("src/ssl/tomcat.keystore").getAbsolutePath());
					} catch (FileNotFoundException e) {
						throw new IllegalStateException("Cannot load keystore", e);
					}
					connector.setAttribute("clientAuth", "false");
					connector.setAttribute("sslProtocol", "TLS");
					connector.setAttribute("SSLEnabled", true);
				}
			});
		}

	}
----



[[howto-enable-multiple-connectors-in-tomcat]]
=== Enable Multiple Connectors Tomcat
Add a `org.apache.catalina.connector.Connector` to the
`TomcatEmbeddedServletContainerFactory` which can allow multiple connectors eg a HTTP and
HTTPS connector:

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@Bean
	public EmbeddedServletContainerFactory servletContainer() {
		TomcatEmbeddedServletContainerFactory tomcat = new TomcatEmbeddedServletContainerFactory();
		tomcat.addAdditionalTomcatConnectors(createSslConnector());
		return tomcat;
	}

	private Connector createSslConnector() {
		Connector connector = new Connector("org.apache.coyote.http11.Http11NioProtocol");
		Http11NioProtocol protocol = (Http11NioProtocol) connector.getProtocolHandler();
		try {
			File keystore = new ClassPathResource("keystore").getFile();
			File truststore = new ClassPathResource("keystore").getFile();
			connector.setScheme("https");
			connector.setSecure(true);
			connector.setPort(8443);
			protocol.setSSLEnabled(true);
			protocol.setKeystoreFile(keystore.getAbsolutePath());
			protocol.setKeystorePass("changeit");
			protocol.setTruststoreFile(truststore.getAbsolutePath());
			protocol.setTruststorePass("changeit");
			protocol.setKeyAlias("apitester");
			return connector;
		}
		catch (IOException ex) {
			throw new IllegalStateException("can't access keystore: [" + "keystore"
					+ "] or truststore: [" + "keystore" + "]", ex);
		}
	}
----



[[howto-use-tomcat-behind-a-proxy-server]]
=== Use Tomcat behind a front-end proxy server
Spring Boot will automatically configure Tomcat's `RemoteIpValve` if it detects some
environment settings. This allows you to transparently use the standard `x-forwarded-for`
and `x-forwarded-proto` headers that most front-end proxy servers add.

You can switch on the valve by adding some entries to application.properties, e.g.

[indent=0]
----
	server.tomcat.remote_ip_header=x-forwarded-for
	server.tomcat.protocol_header=x-forwarded-proto
----

Alternatively, you can add the `RemoteIpValve` yourself by adding a
`TomcatEmbeddedServletContainerFactory` bean.



[[howto-use-jetty-instead-of-tomcat]]
=== Use Jetty instead of Tomcat
The Spring Boot starters (`spring-boot-starter-web` in particular) use Tomcat as an
embedded container by default. You need to exclude those dependencies and include the
Jetty one instead. Spring Boot provides Tomcat and Jetty dependencies bundled together
as separate starters to help make this process as easy as possible.

Example in Maven:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
		<exclusions>
			<exclusion>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-starter-tomcat</artifactId>
			</exclusion>
		</exclusions>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-jetty</artifactId>
	</dependency>
----

Example in Gradle:

[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
	configurations {
		compile.exclude module: "spring-boot-starter-tomcat"
	}

	dependencies {
		compile("org.springframework.boot:spring-boot-starter-web:{spring-boot-version}")
		compile("org.springframework.boot:spring-boot-starter-jetty:{spring-boot-version}")
		// ...
	}
----



[[howto-configure-jetty]]
=== Configure Jetty
Generally you can follow the advice from
'<<howto-discover-build-in-options-for-external-properties>>' about
`@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at
`EmbeddedServletContainerCustomizer`. The Jetty APIs are quite rich so once you have
access to the `JettyEmbeddedServletContainerFactory` you can modify it in a number
of ways. Or the nuclear option is to add your own `JettyEmbeddedServletContainerFactory`.



[[howto-use-tomcat-8]]
=== Use Tomcat 8
Tomcat 8 works with Spring Boot, but the default is to use Tomcat 7 (so we can support
Java 1.6 out of the box). You should only need to change the classpath to use
Tomcat 8 for it to work. For example, using the starter poms in Maven:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<properties>
		<tomcat.version>8.0.8</tomcat.version>
	</properties>
	<dependencies>
		...
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		...
	</dependencies>
----

change the classpath to use Tomcat 8 for it to work.



[[howto-use-jetty-9]]
=== Use Jetty 9
Jetty 9 works with Spring Boot, but the default is to use Jetty 8 (so we can support
Java 1.6 out of the box). You should only need to change the classpath to use Jetty 9
for it to work.

If you are using the starter poms and parent you can just add the Jetty starter and
change the version properties, e.g. for a simple webapp or service:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<properties>
		<java.version>1.7</java.version>
		<jetty.version>9.1.0.v20131115</jetty.version>
		<servlet-api.version>3.1.0</servlet-api.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
			<exclusions>
				<exclusion>
					<groupId>org.springframework.boot</groupId>
					<artifactId>spring-boot-starter-tomcat</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-jetty</artifactId>
		</dependency>
	</dependencies>
----



[[howto-spring-mvc]]
== Spring MVC



[[howto-write-a-json-rest-service]]
=== Write a JSON REST service
Any Spring `@RestController` in a Spring Boot application should render JSON response by
default as long as Jackson2 is on the classpath. For example:

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@RestController
	public class MyController {

		@RequestMapping("/thing")
		public MyThing thing() {
				return new MyThing();
		}

	}
----

As long as `MyThing` can be serialized by Jackson2 (e.g. a normal POJO or Groovy object)
then `http://localhost:8080/thing` will serve a JSON representation of it by default.
Sometimes in a browser you might see XML responses (but by default only if `MyThing` was
a JAXB object) because browsers tend to send accept headers that prefer XML.



[[howto-write-an-xml-rest-service]]
=== Write an XML REST service
Since JAXB is in the JDK the same example as we used for JSON would work, as long as the
`MyThing` was annotated as `@XmlRootElement`:

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@XmlRootElement
	public class MyThing {
		private String name;
		// .. getters and setters
	}
----

To get the server to render XML instead of JSON you might have to send an
`Accept: text/xml` header (or use a browser).



[[howto-customize-the-jackson-objectmapper]]
=== Customize the Jackson ObjectMapper
Spring MVC (client and server side) uses `HttpMessageConverters` to negotiate content
conversion in an HTTP exchange. If Jackson is on the classpath you already get a default
converter with a vanilla `ObjectMapper`. Spring Boot has some features to make it easier
to customize this behavior.

The smallest change that might work is to just add beans of type
`com.fasterxml.jackson.databind.Module` to your context. They will be registered with the
default `ObjectMapper` and then injected into the default message converter. To replace
the default `ObjectMapper` completely, define a `@Bean` of that type and mark it as
`@Primary`.

In addition, if your context contains any beans of type `ObjectMapper` then all of the
`Module` beans will be registered with all of the mappers. So there is a global mechanism
for contributing custom modules when you add new features to your application.

Finally, if you provide any `@Beans` of type `MappingJackson2HttpMessageConverter` then
they will replace the default value in the MVC configuration. Also, a convenience bean is
provided of type `HttpMessageConverters` (always available if you use the default MVC
configuration) which has some useful methods to access the default and user-enhanced
message converters.

See also the '<<howto-customize-the-responsebody-rendering>>' section and the
{sc-spring-boot-autoconfigure}/web/WebMvcAutoConfiguration.{sc-ext}[`WebMvcAutoConfiguration`]
source code for more details.



[[howto-customize-the-responsebody-rendering]]
=== Customize the @ResponseBody rendering
Spring uses `HttpMessageConverters` to render `@ResponseBody` (or responses from
`@RestController`). You can contribute additional converters by simply adding beans of
that type in a Spring Boot context. If a bean you add is of a type that would have been
included by default anyway (like `MappingJackson2HttpMessageConverter` for JSON
conversions) then it will replace the default value. A convenience bean is provided of
type `HttpMessageConverters` (always available if you use the default MVC configuration)
which has some useful methods to access the default and user-enhanced message converters
(useful, for example if you want to manually inject them into a custom `RestTemplate`).

As in normal MVC usage, any `WebMvcConfigurerAdapter` beans that you provide can also
contribute converters by overriding the `configureMessageConverters` method, but unlike
with normal MVC, you can supply only additional converters that you need (because Spring
Boot uses the same mechanism to contribute its defaults). Finally, if you opt-out of the
Spring Boot default MVC configuration by providing your own `@EnableWebMvc` configuration,
then you can take control completely and do everything manually using
`getMessageConverters` from `WebMvcConfigurationSupport`.

See the {sc-spring-boot-autoconfigure}/web/WebMvcAutoConfiguration.{sc-ext}[`WebMvcAutoConfiguration`]
source code for more details.



[[howto-multipart-file-upload-configuration]]
=== Handling Multipart File Uploads
Spring Boot embraces the Servlet 3 `javax.servlet.http.Part` API to support uploading
files. By default Spring Boot configures Spring MVC with a maximum file of 1Mb per
file and a maximum of 10Mb of file data in a single request. You may override these
values, as well as the location to which intermediate data is stored (e.g., to the `/tmp`
directory) and the threshold past which data is flushed to disk by using the properties
exposed in the `MultipartProperties` class. If you want to specify that files be
unlimited, for example, set the `multipart.maxFileSize` property to `-1`.

The multipart support is helpful when you want to receive multipart encoded file data as
a `@RequestParam`-annotated parameter of type `MultipartFile` in a Spring MVC controller
handler method.

See the {sc-spring-boot-autoconfigure}/web/MultipartAutoConfiguration.{sc-ext}[`MultipartAutoConfiguration`] s
ource for more details.



[[howto-switch-off-the-spring-mvc-dispatcherservlet]]
=== Switch off the Spring MVC DispatcherServlet
Spring Boot wants to serve all content from the root of your application `/` down. If you
would rather map your own servlet to that URL you can do it, but of course you may lose
some of the other Boot MVC features. To add your own servlet and map it to the root
resource just declare a `@Bean` of type `Servlet` and give it the special bean name
`dispatcherServlet` (You can also create a bean of a different type with that name if
you want to switch it off and not replace it).



[[howto-switch-off-default-mvc-configuration]]
=== Switch off the Default MVC configuration
The easiest way to take complete control over MVC configuration is to provide your own
`@Configuration` with the `@EnableWebMvc` annotation. This will leave all MVC
configuration in your hands.



[[howto-customize-view-resolvers]]
=== Customize ViewResolvers
A `ViewResolver` is a core component of Spring MVC, translating view names in
`@Controller` to actual `View` implementations. Note that `ViewResolvers` are mainly
used in UI applications, rather than REST-style services (a `View` is not used to render
a `@ResponseBody`). There are many implementations of `ViewResolver` to choose from, and
Spring on its own is not opinionated about which ones you should use. Spring Boot, on the
other hand, installs one or two for you depending on what it finds on the classpath and
in the application context. The `DispatcherServlet` uses all the resolvers it finds in
the application context, trying each one in turn until it gets a result, so if you are
adding your own you have to be aware of the order and in which position your resolver is
added.

`WebMvcAutoConfiguration` adds the following `ViewResolvers` to your context:

* An `InternalResourceViewResolver` with bean id ``defaultViewResolver''. This one locates
  physical resources that can be rendered using the `DefaultServlet` (e.g. static
  resources and JSP pages if you are using those). It applies a prefix and a suffix to the
  view name and then looks for a physical resource with that path in the servlet context
  (defaults are both empty, but accessible for external configuration via
  `spring.view.prefix` and `spring.view.suffix`). It can be overridden by providing a
  bean of the same type.
* A `BeanNameViewResolver` with id ``beanNameViewResolver''. This is a useful member of the
  view resolver chain and will pick up any beans with the same name as the `View` being
  resolved. It shouldn't be necessary to override or replace it.
* A `ContentNegotiatingViewResolver` with id ``viewResolver'' is only added if there *are*
  actually beans of type `View` present. This is a ``master'' resolver, delegating to all
  the others and attempting to find a match to the ``Accept'' HTTP header sent by the
  client. There is a useful
  https://spring.io/blog/2013/06/03/content-negotiation-using-views[blog about `ContentNegotiatingViewResolver`]
  that you might like to study to learn more, and also look at the source code for detail.
  You can switch off the auto-configured
  `ContentNegotiatingViewResolver` by defining a bean named ``viewResolver''.
* If you use Thymeleaf you will also have a `ThymeleafViewResolver` with id
  ``thymeleafViewResolver''. It looks for resources by surrounding the view name with a
  prefix and suffix (externalized to `spring.thymeleaf.prefix` and
  `spring.thymeleaf.suffix`, defaults ``classpath:/templates/'' and ``.html''
  respectively). It can be overridden by providing a bean of the same name.
* If you use FreeMarker you will also have a `FreeMarkerViewResolver` with id
  ``freeMarkerViewResolver''. It looks for resources in a loader path (externalized to
  `spring.freemarker.templateLoaderPath`, default ``classpath:/templates/'') by
  surrounding the view name with a prefix and suffix (externalized to `spring.freemarker.prefix`
  and `spring.freemarker.suffix`, with empty and ``.ftl'' defaults respectively). It can
  be overridden by providing a bean of the same name.
* If you use Groovy templates (actually if groovy-templates is on your classpath) you will
  also have a `Groovy TemplateViewResolver` with id ``groovyTemplateViewResolver''. It
  looks for resources in a loader path by surrounding the view name with a prefix and
  suffix (externalized to `spring.groovy.template.prefix` and
  `spring.groovy.template.suffix`, defaults ``classpath:/templates/'' and ``.tpl''
  respectively). It can be overriden by providing a bean of the same name.
* If you use Velocity you will also have a `VelocityViewResolver` with id ``velocityViewResolver''.
  It looks for resources in a loader path (externalized to `spring.velocity.resourceLoaderPath`,
  default ``classpath:/templates/'') by surrounding the view name with a prefix and suffix
  (externalized to `spring.velocity.prefix` and `spring.velocity.suffix`, with empty  and ``.vm''
  defaults respectively). It can be overridden by providing a bean of the same name.

Check out {sc-spring-boot-autoconfigure}/web/WebMvcAutoConfiguration.{sc-ext}[`WebMvcAutoConfiguration`],
{sc-spring-boot-autoconfigure}/thymeleaf/ThymeleafAutoConfiguration.{sc-ext}[`ThymeleafAutoConfiguration`],
{sc-spring-boot-autoconfigure}/freemarker/FreeMarkerAutoConfiguration.{sc-ext}[`FreeMarkerAutoConfiguration`],
{sc-spring-boot-autoconfigure}/groovy/template/GroovyTemplateAutoConfiguration.{sc-ext}[`GroovyTemplateAutoConfiguration`] and
{sc-spring-boot-autoconfigure}/velocity/VelocityAutoConfiguration.{sc-ext}[`VelocityAutoConfiguration`]



[[howto-logging]]
== Logging

Spring Boot has no mandatory logging dependence, except for the `commons-logging` API, of
which there are many implementations to choose from. To use http://logback.qos.ch[Logback]
you need to include it, and some bindings for `commons-logging` on the classpath. The
simplest way to do that is through the starter poms which all depend on
`spring-boot-starter-logging`. For a web application you only need
`spring-boot-starter-web` since it depends transitively on the logging starter.
For example, using Maven:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
	</dependency>
----

Spring Boot has a `LoggingSystem` abstraction that attempts to configure logging based on
the content of the classpath. If Logback is available it is the first choice.

If the only change you need to make to logging is to set the levels of various loggers
then you can do that in `application.properties` using the "logging.level" prefix, e.g.

[source,properties,indent=0,subs="verbatim,quotes,attributes"]
----
logging.level.org.springframework.web: DEBUG
logging.level.org.hibernate: ERROR
----

You can also set the location of a file to log to (in addition to the console) using
"logging.file". 

To configure the more fine grained settings of a logging system you need to use the native configuration
format supported by the `LoggingSystem` in question. By default Spring Boot picks up the native
configuration from its default location for the system (e.g. `classpath:/logback.xml` for Logback), but
you can set the location of the config file using the "logging.config" property.


[[howto-configure-logback-for-loggin]]
=== Configure Logback for logging
If you put a `logback.xml` in the root of your classpath it will be
picked up from there. Spring Boot provides a default base
configuration that you can include if you just want to set levels,
e.g.

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<?xml version="1.0" encoding="UTF-8"?>
	<configuration>
		<include resource="org/springframework/boot/logging/logback/base.xml"/>
		<logger name="org.springframework.web" level="DEBUG"/>
	</configuration>
----

If you look at the default `logback.xml` in the spring-boot jar you will see that it uses
some useful System properties which the `LoggingSystem` takes care of creating for you.
These are:

* `${PID}` the current process ID.
* `${LOG_FILE}` if `logging.file` was set in Boot's external configuration.
* `${LOG_PATH}` if `logging.path` was set (representing a directory for
	log files to live in).

Spring Boot also provides some nice ANSI colour terminal output on a console (but not in
a log file) using a custom Logback converter. See the default `base.xml` configuration
for details.

If Groovy is on the classpath you should be able to configure Logback with
`logback.groovy` as well (it will be given preference if present).



[[howto-configure-log4j-for-logging]]
=== Configure Log4j for logging
Spring Boot supports http://logging.apache.org/log4j[Log4j] for logging
configuration, but it has to be on the classpath. If you are using the starter poms for
assembling dependencies that means you have to exclude logback and then include log4j
instead. If you aren't using the starter poms then you need to provide `commons-logging`
(at least) in addition to Log4j.

The simplest path to using Log4j is probably through the starter poms, even though it
requires some jiggling with excludes, e.g. in Maven:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter</artifactId>
		<exclusions>
				<exclusion>
						<groupId>org.springframework.boot</groupId>
						<artifactId>spring-boot-starter-logging</artifactId>
				</exclusion>
		</exclusions>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-log4j</artifactId>
	</dependency>
----

NOTE: The use of the log4j starter gathers together the dependencies for common logging
requirements (e.g. including having Tomcat use `java.util.logging` but configure the
output using Log4j). See the Actuator Log4j Sample for more detail and to see it in
action.



[[howto-data-access]]
== Data Access



[[howto-configure-a-datasource]]
=== Configure a DataSource
To override the default settings just define a `@Bean` of your own of type `DataSource`.
Spring Boot provides a utility builder class `DataSourceBuilder` that can be used
to create one of the standard ones (if it is on the classpath), or you can just create
your own, and bind it to a set of `Environment` properties e.g.

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@Bean
	@ConfigurationProperties(prefix="datasource.mine")
	public DataSource dataSource() {
		return new FancyDataSource();
	}
----

[source,properties,indent=0]
----
	datasource.mine.jdbcUrl=jdbc:h2:mem:mydb
	datasource.mine.user=sa
	datasource.mine.poolSize=30
----

See '<<spring-boot-features.adoc#boot-features-configure-datasource>>' in the
``Spring Boot features'' section and the
{sc-spring-boot-autoconfigure}/jdbc/DataSourceAutoConfiguration.{sc-ext}[`DataSourceAutoConfiguration`]
class for more details.



[[howto-two-datasources]]
=== Configure Two DataSources
Creating more than one data source works the same as creating the first one. You might
want to mark one of them as `@Primary` if you are using the default auto-configuration for
JDBC or JPA (then that one will be picked up by any `@Autowired` injections).

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@Bean
	@Primary
	@ConfigurationProperties(prefix="datasource.primary")
	public DataSource primaryDataSource() {
		return DataSourceBuilder.create().build();
	}

	@Bean
	@ConfigurationProperties(prefix="datasource.secondary")
	public DataSource secondaryDataSource() {
		return DataSourceBuilder.create().build();
	}
----



[[howto-use-spring-data-repositories]]
=== Use Spring Data repositories
Spring Data can create implementations for you of `@Repository` interfaces of various
flavours. Spring Boot will handle all of that for you as long as those `@Repositories`
are included in the same package (or a sub-package) of your `@EnableAutoConfiguration`
class.

For many applications all you will need is to put the right Spring Data dependencies on
your classpath (there is a `spring-boot-starter-data-jpa` for JPA and a
`spring-boot-starter-data-mongodb` for Mongodb), create some repository interfaces to handle your
`@Entity` objects. Examples are in the {github-code}/spring-boot-samples/spring-boot-sample-data-jpa[JPA sample]
or the {github-code}/spring-boot-samples/spring-boot-sample-data-mongodb[Mongodb sample].

Spring Boot tries to guess the location of your `@Repository` definitions, based on the
`@EnableAutoConfiguration` it finds. To get more control, use the `@EnableJpaRepositories`
annotation (from Spring Data JPA).


[[howto-separate-entity-definitions-from-spring-configuration]]
=== Separate @Entity definitions from Spring configuration
Spring Boot tries to guess the location of your `@Entity` definitions, based on the
`@EnableAutoConfiguration` it finds. To get more control, you can use the `@EntityScan`
annotation, e.g.

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@Configuration
	@EnableAutoConfiguration
	@EntityScan(basePackageClasses=City.class)
	public class Application {

		//...

	}
----



[[howto-configure-jpa-properties]]
=== Configure JPA properties
Spring Data JPA already provides some vendor-independent configuration options (e.g.
for SQL logging) and Spring Boot exposes those, and a few more for hibernate as external
configuration properties. The most common options to set are:

[indent=0,subs="verbatim,quotes,attributes"]
----
	spring.jpa.hibernate.ddl-auto: create-drop
	spring.jpa.hibernate.naming_strategy: org.hibernate.cfg.ImprovedNamingStrategy
	spring.jpa.database: H2
	spring.jpa.show-sql: true
----

(Because of relaxed data binding hyphens or underscores should work equally well as
property keys.) The `ddl-auto` setting is a special case in that it has different
defaults depending on whether you are using an embedded database (`create-drop`) or not
(`none`). In addition all properties in `spring.jpa.properties.*` are passed through as
normal JPA properties (with the prefix stripped) when the local `EntityManagerFactory` is
created.

See {sc-spring-boot-autoconfigure}/orm/jpa/HibernateJpaAutoConfiguration.{sc-ext}[`HibernateJpaAutoConfiguration`]
and {sc-spring-boot-autoconfigure}/orm/jpa/JpaBaseConfiguration.{sc-ext}[`JpaBaseConfiguration`]
for more details.



[[howto-use-custom-entity-manager]]
=== Use a custom EntityManagerFactory
To take full control of the configuration of the `EntityManagerFactory`, you need to add
a `@Bean` named ``entityManagerFactory''. Spring Boot auto-configuration switches off its
entity manager based on the presence of a bean of that type.



[[howto-use-two-entity-managers]]
=== Use Two EntityManagers

Even if the default `EntityManagerFactory` works fine, you will need to define a new one
because otherwise the presence of the second bean of that type will switch off the
default. To make it easy to do that you can use the convenient `EntityManagerBuilder`
provided by Spring Boot, or if you prefer you can just use the
`LocalContainerEntityManagerFactoryBean` directly from Spring ORM.

Example:

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	// add two data sources configured as above

	@Bean
	public LocalContainerEntityManagerFactoryBean customerEntityManagerFactory(
			EntityManagerFactoryBuilder builder) {
		return builder
				.dataSource(customerDataSource())
				.packages(Customer.class)
				.persistenceUnit("customers")
				.build();
	}

	@Bean
	public LocalContainerEntityManagerFactoryBean orderEntityManagerFactory(
			EntityManagerFactoryBuilder builder) {
		return builder
				.dataSource(orderDataSource())
				.packages(Order.class)
				.persistenceUnit("orders")
				.build();
	}

----

The configuration above almost works on its own. To complete the picture you need to
configure `TransactionManagers` for the two `EntityManagers` as well. One of them could
be picked up by the default `JpaTransactionManager` in Spring Boot if you mark it as
`@Primary`. The other would have to be explicitly injected into a new instance. Or you
might be able to use a JTA transaction manager spanning both.



[[howto-use-traditional-persistence-xml]]
=== Use a traditional persistence.xml
Spring doesn't require the use of XML to configure the JPA provider, and Spring Boot
assumes you want to take advantage of that feature. If you prefer to use `persistence.xml`
then you need to define your own `@Bean` of type `LocalEntityManagerFactoryBean` (with
id ``entityManagerFactory'', and set the persistence unit name there.

See
https://github.com/spring-projects/spring-boot/blob/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/orm/jpa/JpaBaseConfiguration.java[`JpaBaseConfiguration`]
for the default settings.



[[howto-use-spring-data-jpa--and-mongo-repositories]]
=== Use Spring Data JPA and Mongo repositories

Spring Data JPA and Spring Data Mongo can both create `Repository` implementations for you
automatically. If they are both present on the classpath, you might have to do some extra
configuration to tell Spring Boot which one (or both) you want to create repositories for
you. The most explicit way to do that is to use the standard Spring Data
`@Enable*Repositories` and tell it the location of your `Repository` interfaces
(where ``*'' is ``Jpa'' or ``Mongo'' or both).

There are also flags `spring.data.*.repositories.enabled` that you can use to switch the
auto-configured repositories on and off in external configuration.  This is useful for
instance in case you want to switch off the Mongo repositories and still use the
auto-configured `MongoTemplate`.

The same obstacle and the same features exist for other auto-configured Spring Data
repository types (Elasticsearch, Solr). Just change the names of the annotations and flags
respectively.



[[howto-database-initialization]]
== Database initialization
An SQL database can be initialized in different ways depending on what your stack is. Or
of course you can do it manually as long as the database is a separate process.



[[howto-initialize-a-database-using-jpa]]
=== Initialize a database using JPA
JPA has features for DDL generation, and these can be set up to run on startup against the
database. This is controlled through two external properties:

* `spring.jpa.generate-ddl` (boolean) switches the feature on and off and is vendor
  independent.
* `spring.jpa.hibernate.ddl-auto` (enum) is a Hibernate feature that controls the
  behavior in a more fine-grained way. See below for more detail.



[[howto-initialize-a-database-using-hibernate]]
=== Initialize a database using Hibernate
You can set `spring.jpa.hibernate.ddl-auto` explicitly and the standard Hibernate property
values are `none`, `validate`, `update`, `create-drop`. Spring Boot chooses a default
value for you based on whether it thinks your database is embedded (default `create-drop`)
or not (default `none`). An embedded database is detected by looking at the `Connection`
type: `hsqldb`, `h2` and `derby` are embedded, the rest are not. Be careful when switching
from in-memory to a ``real'' database that you don't make assumptions about the existence of
the tables and data in the new platform. You either have to set `ddl-auto` explicitly, or
use one of the other mechanisms to initialize the database.

In addition, a file named `import.sql` in the root of the classpath will be executed on
startup. This can be useful for demos and for testing if you are careful, but probably
not something you want to be on the classpath in production. It is a Hibernate feature
(nothing to do with Spring).


[[howto-intialize-a-database-using-spring-jdbc]]
=== Initialize a database using Spring JDBC
Spring JDBC has a `DataSource` initializer feature. Spring Boot enables it by default and
loads SQL from the standard locations `schema.sql` and `data.sql` (in the root of the
classpath). In addition Spring Boot will load the `schema-${platform}.sql`
and `data-${platform}.sql` files (if present), where
`platform` is the value of `spring.datasource.platform`, e.g. you might choose to set
it to the vendor name of the database (`hsqldb`, `h2`, `oracle`, `mysql`,
`postgresql` etc.). Spring Boot enables the failfast feature of the Spring JDBC
initializer by default, so if the scripts cause exceptions the application will fail
to start. The script locations can be changed by setting `spring.datasource.schema` and
`spring.datasource.data`, and neither location will be processed if
`spring.datasource.initialize=false`.

To disable the failfast you can set `spring.datasource.continueOnError=true`. This can be
useful once an application has matured and been deployed a few times, since the scripts
can act as ``poor man's migrations'' -- inserts that fail mean that the data is already
there, so there would be no need to prevent the application from running, for instance.

If you want to use the `schema.sql` initialization in a JPA app (with
Hibernate) then `ddl-auto=create-drop` will lead to errors if
Hibernate tries to create the same tables.  To avoid those errors set
`ddl-auto` explicitly to "" (preferable) or "none". Whether or not you use
`ddl-auto=create-drop` you can always use `data.sql` to initialize new
data.



[[howto-initialize-a-spring-batch-database]]
=== Initialize a Spring Batch database
If you are using Spring Batch then it comes pre-packaged with SQL initialization scripts
for most popular database platforms. Spring Boot will detect your database type, and
execute those scripts by default, and in this case will switch the fail fast setting to
false (errors are logged but do not prevent the application from starting). This is
because the scripts are known to be reliable and generally do not contain bugs, so errors
are ignorable, and ignoring them makes the scripts idempotent. You can switch off the
initialization explicitly using `spring.batch.initializer.enabled=false`.



[[howto-use-a-higher-level-database-migration-tool]]
=== Use a higher level database migration tool
Spring Boot works fine with higher level migration tools http://flywaydb.org/[Flyway]
(SQL-based) and http://www.liquibase.org/[Liquibase] (XML). In general we prefer
Flyway because it is easier on the eyes, and it isn't very common to need platform
independence: usually only one or at most couple of platforms is needed.

[[howto-execute-flyway-database-migrations-on-startup]]
==== Execute Flyway database migrations on startup
To automatically run Flyway database migrations on startup, add the
`org.flywaydb:flyway-core` to your classpath.

The migrations are scripts in the form `V<VERSION>__<NAME>.sql` (with `<VERSION>` an
underscore-separated version, e.g. ``1'' or ``2_1''). By default they live in a folder
`classpath:db/migration` but you can modify that using `flyway.locations` (a list). See
the Flyway class from flyway-core for details of available settings like schemas etc. In
addition Spring Boot provides a small set of properties in
{sc-spring-boot-autoconfigure}/flyway/FlywayProperties.{sc-ext}[`FlywayProperties`]
that can be used to disable the migrations, or switch off the location checking.

By default Flyway will autowire the (`@Primary`) `DataSource` in your context and
use that for migrations. If you like to use a different `DataSource` you can create
one and mark its `@Bean` as `@FlywayDataSource` - if you do that remember to create
another one and mark it as `@Primary` if you want 2 data sources.
Or you can use Flyway's native `DataSource` by setting `flyway.[url,user,password]`
in external properties.

There is a {github-code}/spring-boot-samples/spring-boot-sample-flyway[Flyway sample] so
you can see how to set things up.



[[howto-execute-liquibase-database-migrations-on-startup]]
==== Execute Liquibase database migrations on startup
To automatically run Liquibase database migrations on startup, add the
`org.liquibase:liquibase-core` to your classpath.

The master change log is by default read from `db/changelog/db.changelog-master.yaml` but
can be set using `liquibase.change-log`. See
{sc-spring-boot-autoconfigure}/liquibase/LiquibaseProperties.{sc-ext}[`LiquibaseProperties`]
for details of available settings like contexts, default schema etc.

There is a {github-code}/spring-boot-samples/spring-boot-sample-liquibase[Liquibase sample] so
you can see how to set things up.



[[howto-batch-applications]]
== Batch applications



[[howto-execute-spring-batch-jobs-on-startup]]
=== Execute Spring Batch jobs on startup
Spring Batch auto configuration is enabled by adding `@EnableBatchProcessing`
(from Spring Batch) somewhere in your context.

By default it executes *all* `Jobs` in the application context on startup (see
{sc-spring-boot-autoconfigure}/batch/JobLauncherCommandLineRunner.{sc-ext}[JobLauncherCommandLineRunner]
for details). You can narrow down to a specific job or jobs by specifying
`spring.batch.job.names` (comma separated job name patterns).

If the application context includes a `JobRegistry` then the jobs in
`spring.batch.job.names` are looked up in the registry instead of being autowired from the
context. This is a common pattern with more complex systems where multiple jobs are
defined in child contexts and registered centrally.

See
{sc-spring-boot-autoconfigure}/batch/BatchAutoConfiguration.{sc-ext}[BatchAutoConfiguration]
and
https://github.com/spring-projects/spring-batch/blob/master/spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/EnableBatchProcessing.java[@EnableBatchProcessing]
for more details.



[[howto-actuator]]
== Actuator



[[howto-change-the-http-port-or-address-of-the-actuator-endpoints]]
=== Change the HTTP port or address of the actuator endpoints
In a standalone application the Actuator HTTP port defaults to the same as the main HTTP
port. To make the application listen on a different port set the external property
`management.port`. To listen on a completely different network address (e.g. if you have
an internal network for management and an external one for user applications) you can
also set `management.address` to a valid IP address that the server is able to bind to.

For more detail look at the
{sc-spring-boot-actuator}/autoconfigure/ManagementServerProperties.{sc-ext}[`ManagementServerProperties`]
source code and
'<<production-ready-features.adoc#production-ready-customizing-management-server-port>>'
in the ``Production-ready features'' section.



[[howto-customize-the-whitelabel-error-page]]
=== Customize the ``whitelabel'' error page
The Actuator installs a ``whitelabel'' error page that you will see in browser client if
you encounter a server error (machine clients consuming JSON and other media types should
see a sensible response with the right error code). To switch it off you can set
`error.whitelabel.enabled=false`, but normally in addition or alternatively to that you
will want to add your own error page replacing the whitelabel one. Exactly how you do this
depends on the templating technology that you are using. For example, if you are using
Thymeleaf you would add an `error.html` template and if you are using FreeMarker you would
add an `error.ftl` template. In general what you need is a `View` that resolves with a name
of `error`, and/or a `@Controller` that handles the `/error` path. Unless you replaced some
of the default configuration you should find a `BeanNameViewResolver` in your
`ApplicationContext` so a `@Bean` with id `error` would be a simple way of doing that.
Look at {sc-spring-boot-autoconfigure}/web/ErrorMvcAutoConfiguration.{sc-ext}[`ErrorMvcAutoConfiguration`] for more options.



[[howto-security]]
== Security


[[howto-switch-off-spring-boot-security-configuration]]
=== Switch off the Spring Boot security configuration
If you define a `@Configuration` with `@EnableWebSecurity` anywhere in your application
it will switch off the default webapp security settings in Spring Boot. To tweak the
defaults try setting properties in `security.*` (see
{sc-spring-boot-autoconfigure}/security/SecurityProperties.{sc-ext}[`SecurityProperties`]
for details of available settings) and `SECURITY` section of
<<common-application-properties-security,Common application properties>>.



[[howto-change-the-authenticationmanager-and-add-user-accounts]]
=== Change the AuthenticationManager and add user accounts
If you provide a `@Bean` of type `AuthenticationManager` the default one will not be
created, so you have the full feature set of Spring Security available (e.g.
http://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#jc-authentication[various authentication options]).

Spring Security also provides a convenient `AuthenticationManagerBuilder` which can be
used to build an `AuthenticationManager` with common options. The recommended way to
use this in a webapp is to inject it into a void method in a
`WebSecurityConfigurerAdapter`, e.g.

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@Configuration
	public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

		@Autowired
		public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
				auth.inMemoryAuthentication()
					.withUser("barry").password("password").roles("USER"); // ... etc.
		}

		// ... other stuff for application security

	}
----

You will get the best results if you put this in a nested class, or a standalone class
(i.e. not mixed in with a lot of other `@Beans` that might be allowed to influence the
order of instantiation). The {github-code}/spring-boot-samples/spring-boot-sample-web-secure[secure web sample]
is a useful template to follow.



[[howto-enable-https]]
=== Enable HTTPS when running behind a proxy server
Ensuring that all your main endpoints are only available over HTTPS is an important
chore for any application. If you are using Tomcat as a servlet container, then
Spring Boot will add Tomcat's own `RemoteIpValve` automatically if it detects some
environment settings, and you should be able to rely on the `HttpServletRequest` to
report whether it is secure or not (even downstream of a proxy server that handles the
real SSL termination). The standard behavior is determined by the presence or absence of
certain request headers (`x-forwarded-for` and `x-forwarded-proto`), whose names are
conventional, so it should work with most front end proxies. You can switch on the valve
by adding some entries to `application.properties`, e.g.

[source,properties,indent=0]
----
	server.tomcat.remote_ip_header=x-forwarded-for
	server.tomcat.protocol_header=x-forwarded-proto
----

(The presence of either of those properties will switch on the valve. Or you can add the
`RemoteIpValve` yourself by adding a `TomcatEmbeddedServletContainerFactory` bean.)

Spring Security can also be configured to require a secure channel for all (or some
requests). To switch that on in a Spring Boot application you just need to set
`security.require_https` to `true` in `application.properties`.



[[howto-hotswapping]]
== Hot swapping



[[howto-reload-static-content]]
=== Reload static content
There are several options for hot reloading. Running in an IDE (especially with debugging
on) is a good way to do development (all modern IDEs allow reloading of static resources
and usually also hot-swapping of Java class changes). The
<<build-tool-plugins.adoc#build-tool-plugins, Maven and Gradle plugins>> also
support running from the command line with reloading of static files. You can use that
with an external css/js compiler process if you are writing that code with higher level
tools.



[[howto-reload-thymeleaf-content]]
=== Reload Thymeleaf templates without restarting the container
If you are using Thymeleaf, then set `spring.thymeleaf.cache` to `false`. See
{sc-spring-boot-autoconfigure}/thymeleaf/ThymeleafAutoConfiguration.{sc-ext}[`ThymeleafAutoConfiguration`]
for other Thymeleaf customization options.



[[howto-reload-freemarker-content]]
=== Reload FreeMarker templates without restarting the container
If you are using FreeMarker, then set `spring.freemarker.cache` to `false`. See
{sc-spring-boot-autoconfigure}/freemarker/FreeMarkerAutoConfiguration.{sc-ext}[`FreeMarkerAutoConfiguration`]
for other FreeMarker customization options.



[[howto-reload-groovy-template-content]]
=== Reload Groovy templates without restarting the container
If you are using Groovy templates, then set `spring.groovy.template.cache` to `false`. See
{sc-spring-boot-autoconfigure}/groovy/template/GroovyTemplateAutoConfiguration.{sc-ext}[`GroovyTemplateAutoConfiguration`]
for other Groovy customization options.



[[howto-reload-velocity-content]]
=== Reload Velocity templates without restarting the container
If you are using Velocity, then set `spring.velocity.cache` to `false`. See
{sc-spring-boot-autoconfigure}/velocity/VelocityAutoConfiguration.{sc-ext}[`VelocityAutoConfiguration`]
for other Velocity customization options.



[[howto-reload-java-classes-without-restarting]]
=== Reload Java classes without restarting the container
Modern IDEs (Eclipse, IDEA, etc.) all support hot swapping of bytecode, so if you make a
change that doesn't affect class or method signatures it should reload cleanly with no
side effects.

https://github.com/spring-projects/spring-loaded[Spring Loaded] goes a little further in
that it can reload class definitions with changes in the method signatures. With some
customization it can force an `ApplicationContext` to refresh itself (but there is no
general mechanism to ensure that would be safe for a running application anyway, so it
would only ever be a development time trick probably).


[[howto-reload-springloaded-gradle-and-intellij]]
==== Configuring Spring Loaded for use with Gradle and IntelliJ
You need to jump though a few hoops if you want to use Spring Loaded in combination with
Gradle and IntelliJ. By default, IntelliJ will compile classes into a different location
than Gradle, causing Spring Loaded monitoring to fail.

To configure IntelliJ correctly you can use the `idea` Gradle plugin:

[source,groovy,indent=0,subs="verbatim,attributes"]
----
	buildscript {
		repositories { mavenCentral() }
		dependencies {
			classpath "org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}"
			classpath 'org.springframework:springloaded:1.2.0.RELEASE'
		}
	}

	apply plugin: 'idea'

	idea {
		module {
			inheritOutputDirs = false
			outputDir = file("$buildDir/classes/main/")
		}
	}

	// ...

----

NOTE: Intellij must be configured to use the same Java version as the command line Gradle
task and `springloaded` *must* be included as a `buildscript` dependency.

You can also additionally enable ``Make Project Automatically'' inside  Intellij to
automatically compile your code whenever a file is saved.



[[howto-build]]
== Build



[[howto-customize-dependency-versions-with-maven]]
=== Customize dependency versions with Maven
If you use a Maven build that inherits directly or indirectly from `spring-boot-dependencies`
(for instance `spring-boot-starter-parent`) but you want to override a specific
third-party dependency you can add appropriate `<properties>` elements. Browse
the {github-code}/spring-boot-dependencies/pom.xml[`spring-boot-dependencies`]
POM for a complete list of properties. For example, to pick a different `slf4j` version
you would add the following:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<properties>
		<slf4j.version>1.7.5<slf4j.version>
	</properties>
----

NOTE: this only works if your Maven project inherits (directly or indirectly) from
`spring-boot-dependencies`. If you have added `spring-boot-dependencies` in your
own `dependencyManagement` section with `<scope>import</scope>` you have to redefine
the artifact yourself instead of overriding the property	.

WARNING: Each Spring Boot release is designed and tested against a specific set of
third-party dependencies. Overriding versions may cause compatibility issues.



[[howto-create-an-executable-jar-with-maven]]
=== Create an executable JAR with Maven
The `spring-boot-maven-plugin` can be used to create an executable ``fat'' JAR. If you
are using the `spring-boot-starter-parent` POM you can simply declare the plugin and
your jars will be repackaged:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
----

If you are not using the parent POM you can still use the plugin, however, you must
additionally add an `<executions>` section:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<version>{spring-boot-version}</version>
				<executions>
					<execution>
						<goals>
							<goal>repackage</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
----

See the {spring-boot-maven-plugin-site}/usage.html[plugin documentation] for full usage
details.


[[howto-create-an-additional-executable-jar]]
=== Create an additional executable JAR
If you want to use your project as a library jar for other projects to depend on, and in
addition have an executable (e.g. demo) version of it, you will want to configure the
build in a slightly different way.

For Maven the normal JAR plugin and the Spring Boot plugin both have a ``classifier''
configuration that you can add to create an additional JAR. Example (using the Spring
Boot Starter Parent to manage the plugin versions and other configuration defaults):

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<classifier>exec</classifier>
				</configuration>
			</plugin>
		</plugins>
	</build>
----

Two jars are produced, the default one, and an executable one using the Boot plugin with
classifier ``exec''.

For Gradle users the steps are similar. Example:

[source,groovy,indent=0,subs="verbatim,attributes"]
----
	bootRepackage  {
		classifier = 'exec'
	}
----



[[howto-extract-specific-libraries-when-an-executable-jar-runs]]
=== Extract specific libraries when an executable jar runs
Most nested libraries in an executable jar do not need to be unpacked in order to run,
however, certain libraries can have problems. For example, JRuby includes its own nested
jar support which assumes that the `jruby-complete.jar` is always directly available as a
file in its own right.

To deal with any problematic libraries, you can flag that specific nested jars should be
automatically unpacked to the ``temp folder'' when the executable jar first runs.

For example, to indicate that JRuby should be flagged for unpack using the Maven Plugin
you would add the following configuration:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<requiresUnpack>
						<dependency>
							<groupId>org.jruby</groupId>
							<artifactId>jruby-complete</artifactId>
						</dependency>
					</requiresUnpack>
				</configuration>
			</plugin>
		</plugins>
	</build>
----

And to do that same with Gradle:

[source,groovy,indent=0,subs="verbatim,attributes"]
----
	springBoot  {
		requiresUnpack = ['org.jruby:jruby-complete']
	}
----



[[howto-create-a-nonexecutable-jar]]
=== Create a non-executable JAR with exclusions
Often if you have an executable and a non-executable jar as build products, the executable
version will have additional configuration files that are not needed in a library jar.
E.g. the `application.yml` configuration file might excluded from the non-executable JAR.

Here's how to do that in Maven:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<classifier>exec</classifier>
				</configuration>
			</plugin>
			<plugin>
				<artifactId>maven-jar-plugin</artifactId>
				<executions>
					<execution>
						<id>exec</id>
						<phase>package</phase>
						<goals>
							<goal>jar</goal>
						</goals>
						<configuration>
							<classifier>exec</classifier>
						</configuration>
					</execution>
					<execution>
						<phase>package</phase>
						<goals>
							<goal>jar</goal>
						</goals>
						<configuration>
							<!-- Need this to ensure application.yml is excluded -->
							<forceCreation>true</forceCreation>
							<excludes>
								<exclude>application.yml</exclude>
							</excludes>
						</configuration>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
----

In Gradle you can create a new JAR archive with standard task DSL features, and then have
the `bootRepackage` task depend on that one using its `withJarTask` property:

[source,groovy,indent=0,subs="verbatim,attributes"]
----
	jar {
		baseName = 'spring-boot-sample-profile'
		version =  '0.0.0'
		excludes = ['**/application.yml']
	}

	task('execJar', type:Jar, dependsOn: 'jar') {
		baseName = 'spring-boot-sample-profile'
		version =  '0.0.0'
		classifier = 'exec'
		from sourceSets.main.output
	}

	bootRepackage  {
		withJarTask = tasks['execJar']
	}
----



[[howto-remote-debug-maven-run]]
=== Remote debug a Spring Boot application started with Maven
To attach a remote debugger to a Spring Boot application started with Maven you can use
the `jvmArguments` property of the {spring-boot-maven-plugin-site}/[maven plugin].

Check {spring-boot-maven-plugin-site}/examples/run-debug.html[this example] for more details.



[[howto-remote-debug-gradle-run]]
=== Remote debug a Spring Boot application started with Gradle
To attach a remote debugger to a Spring Boot application started with Gradle you can use
the `applicationDefaultJvmArgs` in `build.gradle` or `--debug-jvm` command line option.

`build.gradle`:

[source,groovy,indent=0,subs="verbatim,attributes"]
----
	applicationDefaultJvmArgs = [
	    "-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005"
	]
----


Command line:

[indent=0]
----
	$ gradle run --debug-jvm
----


Check {gradle-userguide}/application_plugin.html[Gradle Application Plugin] for more
details.



[[howto-build-an-executable-archive-with-ant]]
=== Build an executable archive with Ant
To build with Ant you need to grab dependencies, compile and then create a jar or war
archive as normal. To make it executable:

. Use the appropriate launcher as a `Main-Class`, e.g. `JarLauncher` for a jar file, and
  specify the other properties it needs as manifest entries, principally a `Start-Class`.

. Add the runtime dependencies in a nested ``lib'' directory (for a jar) and the
  `provided` (embedded container) dependencies in a nested `lib-provided` directory.
  Remember *not* to compress the entries in the archive.

. Add the `spring-boot-loader` classes at the root of the archive (so the `Main-Class`
  is available).

Example:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
	<target name="build" depends="compile">
		<copy todir="target/classes/lib">
			<fileset dir="lib/runtime" />
		</copy>
		<jar destfile="target/spring-boot-sample-actuator-${spring-boot.version}.jar" compress="false">
			<fileset dir="target/classes" />
			<fileset dir="src/main/resources" />
			<zipfileset src="lib/loader/spring-boot-loader-jar-${spring-boot.version}.jar" />
			<manifest>
				<attribute name="Main-Class" value="org.springframework.boot.loader.JarLauncher" />
				<attribute name="Start-Class" value="${start-class}" />
			</manifest>
		</jar>
	</target>
----

The Actuator Sample has a `build.xml` that should work if you run it with

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ ant -lib <path_to>/ivy-2.2.jar
----

after which you can run the application with

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ java -jar target/*.jar
----



[[howto-traditional-deployment]]
== Traditional deployment



[[howto-create-a-deployable-war-file]]
=== Create a deployable war file
Use the `SpringBootServletInitializer` base class, which is picked up by Spring's
Servlet 3.0 support on deployment. Add an extension of that to your project and build a
war file as normal. For more detail, see the
http://spring.io/guides/gs/convert-jar-to-war[``Converting a jar Project to a war''] guide
on the spring.io website and the sample below.

The war file can also be executable if you use the Spring Boot build tools. In that case
the embedded container classes (to launch Tomcat for instance) have to be added to the
war in a `lib-provided` directory. The tools will take care of that as long as the
dependencies are marked as ``provided'' in Maven or Gradle. Here's a Maven example
{github-code}/spring-boot-samples/spring-boot-sample-traditional/pom.xml[in the Boot Samples].



[[howto-create-a-deployable-war-file-for-older-containers]]
=== Create a deployable war file for older servlet containers
Older Servlet containers don't have support for the `ServletContextInitializer` bootstrap
process used in Servlet 3.0. You can still use Spring and Spring Boot in these containers
but you are going to need to add a `web.xml` to your application and configure it to load
an `ApplicationContext` via a `DispatcherServlet`.



[[howto-convert-an-existing-application-to-spring-boot]]
=== Convert an existing application to Spring Boot
For a non-web application it should be easy (throw away the code that creates your
`ApplicationContext` and replace it with calls to `SpringApplication` or
`SpringApplicationBuilder`). Spring MVC web applications are generally amenable to first
creating a deployable war application, and then migrating it later to an executable war
and/or jar. Useful reading is in the http://spring.io/guides/gs/convert-jar-to-war/[Getting
Started Guide on Converting a jar to a war].

Create a deployable war by extending `SpringBootServletInitializer` (e.g. in a class
called `Application`), and add the Spring Boot `@EnableAutoConfiguration` annotation.
Example:

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	@Configuration
	@EnableAutoConfiguration
	@ComponentScan
	public class Application extends SpringBootServletInitializer {

		@Override
		protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
			return application.sources(Application.class);
		}

	}
----

Remember that whatever you put in the `sources` is just a Spring `ApplicationContext` and
normally anything that already works should work here. There might be some beans you can
remove later and let Spring Boot provide its own defaults for them, but it should be
possible to get something working first.

Static resources can be moved to `/public` (or `/static` or `/resources` or
`/META-INF/resources`) in the classpath root. Same for `messages.properties` (Spring Boot
detects this automatically in the root of the classpath).

Vanilla usage of Spring `DispatcherServlet` and Spring Security should require no further
changes. If you have other features in your application, using other servlets or filters
for instance, then you may need to add some configuration to your `Application` context,
replacing those elements from the `web.xml` as follows:

* A `@Bean` of type `Servlet` or `ServletRegistrationBean` installs that bean in the
  container as if it was a `<servlet/>` and `<servlet-mapping/>` in `web.xml`.
* A `@Bean` of type `Filter` or `FilterRegistrationBean` behaves similarly (like a
  `<filter/>` and `<filter-mapping/>`.
* An `ApplicationContext` in an XML file can be added to an `@Import` in your
  `Application`. Or simple cases where annotation configuration is heavily used already
  can be recreated in a few lines as `@Bean` definitions.

Once the war is working we make it executable by adding a `main` method to our
`Application`, e.g.

[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
	public static void main(String[] args) {
		SpringApplication.run(Application.class, args);
	}
----

Applications can fall into more than one category:

* Servlet 3.0 applications with no `web.xml`.
* Applications with a `web.xml`.
* Applications with a context hierarchy.
* Applications without a context hierarchy.

All of these should be amenable to translation, but each might require slightly different
tricks.

Servlet 3.0 applications might translate pretty easily if they already use the Spring
Servlet 3.0 initializer support classes. Normally all the code from an existing
`WebApplicationInitializer` can be moved into a `SpringBootServletInitializer`. If your
existing application has more than one `ApplicationContext` (e.g. if it uses
`AbstractDispatcherServletInitializer`) then you might be able to squash all your context
sources into a single `SpringApplication`. The main complication you might encounter is if
that doesn't work and you need to maintain the context hierarchy. See the
<<howto-build-an-application-context-hierarchy, entry on building a hierarchy>> for
examples. An existing parent context that contains web-specific features will usually
need to be broken up so that all the `ServletContextAware` components are in the child
context.

Applications that are not already Spring applications might be convertible to a Spring
Boot application, and the guidance above might help, but your mileage may vary.
