474 lines
18 KiB
Markdown
474 lines
18 KiB
Markdown
# Spring Boot - Core
|
||
This module provides the core features for the other modules in the project. It is
|
||
relatively unopinionated and it has minimal required dependencies which makes it usable
|
||
as a stand-alone library for anyone whose tastes diverge from ours.
|
||
|
||
## SpringApplication
|
||
The `SpringApplication` class provides a convenient way to bootstrap a Spring application
|
||
that will be started from a `main()` method. In many situations you can just delegate
|
||
to the static `SpringApplication.run` method:
|
||
|
||
```java
|
||
public static void main(String[] args) {
|
||
SpringApplication.run(MySpringConfiguration.class, args);
|
||
}
|
||
```
|
||
|
||
When you application starts you should see something similar to the following:
|
||
|
||
```
|
||
. ____ _ __ _ _
|
||
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
|
||
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
|
||
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
|
||
' |____| .__|_| |_|_| |_\__, | / / / /
|
||
=========|_|==============|___/=/_/_/_/
|
||
:: Spring Boot :: v0.0.0.BUILD.SNAPSHOT
|
||
|
||
2013-07-31 00:08:16.117 INFO 56603 --- [ main] o.s.b.s.app.SampleApplication : Starting SampleApplication v0.1.0 on mycomputer with PID 56603 (/apps/myapp.jar started by pwebb)
|
||
2013-07-31 00:08:16.166 INFO 56603 --- [ main] ationConfigEmbeddedWebApplicationContext : Refreshing org.springframework.boot.context.embedded.AnnotationConfigEmbeddedWebApplicationContext@6e5a8246: startup date [Wed Jul 31 00:08:16 PDT 2013]; root of context hierarchy
|
||
```
|
||
|
||
By default `INFO` logging messages will shown, including some relevant startup details
|
||
such as the user that launched the application.
|
||
|
||
### Customizing SpringApplication
|
||
If the SpringApplication defaults aren't to your taste you can instead create a local
|
||
instance and customize it. For example, to turn off the banner you would write:
|
||
|
||
```java
|
||
public static void main(String[] args) {
|
||
SpringApplication app = new SpringApplication(MySpringConfiguration.class);
|
||
app.setShowBanner(false);
|
||
app.run(args);
|
||
}
|
||
```
|
||
|
||
Note that the constructor arguments passed to `SpringApplication` are configuration
|
||
sources for spring beans. In most cases these will be references to `@Configuration`
|
||
classes, but they could also be references to XML configuration or to packages that
|
||
should be scanned.
|
||
|
||
See the `SpringApplication` Javadoc for a complete list of the configuration options
|
||
|
||
### Accessing command line properties
|
||
By default `SpringApplication` will convert any command line option arguments (starting
|
||
with '--', e.g. `--server.port=9000`) to a `PropertySource` and add it to the Spring
|
||
`Environment` with highest priority (taking precedence and overriding values from other
|
||
sources). Properties in the `Environment` (including System properties and OS environment
|
||
variables) can always be injected into Spring components using `@Value` with
|
||
placeholders, e.g.
|
||
|
||
```java
|
||
import org.springframework.stereotype.*
|
||
import org.springframework.beans.factory.annotation.*
|
||
|
||
@Component
|
||
public class MyBean {
|
||
|
||
@Value("${name}")
|
||
private String name;
|
||
// Running 'java -jar myapp.jar --name=Spring' will set this to "Spring"
|
||
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### CommandLineRunner beans
|
||
If you want access to the raw command line argument, or you need to run some specific
|
||
code once the `SpringApplication` has started you can implement the `CommandLineRunner`
|
||
interface. The `run(String... args)` method will be called on all spring beans
|
||
implementing this interface.
|
||
|
||
```java
|
||
import org.springframework.boot.*
|
||
import org.springframework.stereotype.*
|
||
|
||
@Component
|
||
public class MyBean implements CommandLineRunner {
|
||
|
||
public void run(String... args) {
|
||
// Do something...
|
||
}
|
||
|
||
}
|
||
```
|
||
|
||
You can additionally implement the `org.springframework.core.Ordered` interface or use
|
||
the `org.springframework.core.annotation.Order` annotation if several `CommandLineRunner`
|
||
beans are defined that must be called in a specific order.
|
||
|
||
### Application Exit
|
||
Each `SpringApplication` will register a shutdown hook with the JVM to ensure that the
|
||
`ApplicationContext` is closed gracefully on exit. All the standard Spring lifecycle
|
||
callbacks (such as the `DisposableBean` interface, or the `@PreDestroy` annotation)
|
||
can be used.
|
||
|
||
In addition, beans may implement the `org.springframework.boot.ExitCodeGenerator`
|
||
interface if they with to return a specific exit code when the application ends.
|
||
|
||
### Externalized Configuration
|
||
A `SpringApplication` will load properties from `application.properties` in the root of
|
||
your classpath and add them to the Spring `Environment`. The actual search path for the
|
||
files is:
|
||
|
||
1. classpath root
|
||
2. current directory
|
||
3. classpath `/config` package
|
||
4. `/config` subdir of the current directory.
|
||
|
||
The list is ordered by decreasing precedence (so properties can be overridden by others
|
||
with the same name defined in later locations). In addition, profile specific properties
|
||
can also be defined using the naming convention `application-{profile}.properties`
|
||
(properties from these files override the default ones).
|
||
|
||
The values in `application.properties` are filtered through the existing `Environment`
|
||
when they are used so you can refer back to previously defined values (e.g. from System
|
||
properties).
|
||
|
||
```
|
||
app.name: MyApp
|
||
app.description: ${app.name} is a Spring Boot application
|
||
```
|
||
|
||
If you don't like `application.properties` as the configuration file name you can
|
||
switch to another by specifying `spring.config.name` environment property. You can also
|
||
refer to an explicit location using the `spring.config.location` environment property.
|
||
|
||
$ java -jar myproject.jar --spring.config.name=myproject
|
||
|
||
|
||
> **Note:** You can also use '.yaml' files as an alternative to '.properties' (see
|
||
> [below](#using-yaml-instead-of-properties))_
|
||
|
||
### Setting the Default Spring Profile
|
||
Spring Profiles are a way to segregate parts of the application configuration and make it
|
||
only available in certain environments. Any `@Component` that is marked with `@Profile`
|
||
will only be loaded in the profile specified by the latter annotation.
|
||
|
||
A `SpringApplication` takes this a stage further, in that you can use a
|
||
`spring.profiles.active` `Environment` property to specify which profiles are active.
|
||
You can specify the property in any of the usual ways, for example you could include
|
||
it in your `application.properties`:
|
||
|
||
```
|
||
spring.profiles.active=dev,hsqldb
|
||
```
|
||
|
||
or specify on the command line using the switch `--spring.profiles.active=dev,hsqldb`.
|
||
|
||
### Application Context Initializers
|
||
Spring provides a convenient `ApplicationContextInitializer` interface that can be used
|
||
to customize an `ApplicationContext` before it is used. If you need to use an initializer
|
||
with your `SpringApplication` you can use the `addInitializers` method.
|
||
|
||
You can also specify initializers by setting comma-delimited list of class names to the
|
||
`Environment` property `context.initializer.classes` or by using Spring's
|
||
`SpringFactoriesLoader` mechanism.
|
||
|
||
|
||
## Embedded Servlet Container Support
|
||
Spring Boot introduces a new type of Spring `ApplicationContext` that can be used to
|
||
start an embedded servlet container. The `EmbeddedWebApplicationContext` is a special
|
||
type of `WebApplicationContext` that starts the container by searching for a single
|
||
`EmbeddedServletContainerFactory` bean contained within itself. We provide
|
||
`TomcatEmbeddedServletContainerFactory` and `JettyEmbeddedServletContainerFactory`
|
||
implementations for running embedded Tomcat or Jetty.
|
||
|
||
One advantage of using a Spring bean to define the embedded container is that you can use
|
||
all the standard Spring concepts. For example, it becomes trivial to define a Tomcat
|
||
server that sets its port from an injected `@Value`.
|
||
|
||
```java
|
||
@Configuration
|
||
public class MyConfiguration {
|
||
|
||
@Value("${tomcatport:8080}")
|
||
private int port;
|
||
|
||
@Bean
|
||
public EmbeddedServletContainerFactory servletContainer() {
|
||
return new TomcatEmbeddedServletContainerFactory(this.port);
|
||
}
|
||
|
||
}
|
||
```
|
||
|
||
### Customizing Servlet Containers
|
||
Both the Tomcat and Jetty factories extend from the base
|
||
`AbstractEmbeddedServletContainerFactory` class. This provides a uniform way
|
||
to configure both containers.
|
||
|
||
Settings that you would traditionally configure in a `web.xml` or via an implementation
|
||
specific configuration file can now be performed programmatically.
|
||
|
||
```java
|
||
@Bean
|
||
public EmbeddedServletContainerFactory servletContainer() {
|
||
TomcatEmbeddedServletContainerFactory factory = new TomcatEmbeddedServletContainerFactory();
|
||
factory.setPort(9000);
|
||
factory.setSessionTimeout(10, TimeUnit.MINUTES);
|
||
factory.addErrorPages(new ErrorPage(HttpStatus.404, "/notfound.html");
|
||
return factory;
|
||
}
|
||
```
|
||
|
||
In addition, you can also add `ServletContextInitializer` implementations which allow
|
||
you to customize the `javax.servlet.ServletContext` in the same way as any Servlet 3.0
|
||
environment.
|
||
|
||
### Servlets and Filters
|
||
Servlets and Filters can be defined directly as beans with the
|
||
`EmbeddedWebApplicationContext`. By default, if the context contains only a single
|
||
Servlet it will be mapped to '/'. In the case of multiple Servlets beans the bean name
|
||
will be used as a path prefix. Filters will map to '/*'.
|
||
|
||
If convention based mapping is not flexible enough you can use the
|
||
`ServletRegistrationBean` and `FilterRegistrationBean` classes for complete control. You
|
||
can also register items directly if your bean implements the `ServletContextInitializer`
|
||
interface.
|
||
|
||
|
||
## Using YAML instead of Properties
|
||
[YAML](http://yaml.org) is a superset of JSON, and as such is a very convenient format
|
||
for specifying hierarchical configuration data. The `SpringApplication` class will
|
||
automatically support YAML as an alternative to properties whenever you have the
|
||
[SnakeYAML](http://code.google.com/p/snakeyaml/) library on your classpath.
|
||
|
||
### Loading YAML
|
||
Spring Boot provides two convenient classes that can be used to load YAML documents. The
|
||
`YamlPropertiesFactoryBean` will load YAML as `Properties` and the `YamlMapFactoryBean`
|
||
will load YAML as a `Map`.
|
||
|
||
For example, the following YAML document:
|
||
```yaml
|
||
dev:
|
||
url: http://dev.bar.com
|
||
name: Developer Setup
|
||
prod:
|
||
url: http://foo.bar.com
|
||
name: My Cool App
|
||
```
|
||
|
||
Would be transformed into these properties:
|
||
```
|
||
environments.dev.url=http://dev.bar.com
|
||
environments.dev.name=Developer Setup
|
||
environments.prod.url=http://foo.bar.com
|
||
environments.prod.name=My Cool App
|
||
```
|
||
|
||
YAML lists are represented as comma-separated values (useful for simple String values)
|
||
and also as property keys with `[index]` dereferencers, for example this YAML:
|
||
|
||
```yaml
|
||
servers:
|
||
- dev.bar.com
|
||
- foo.bar.com
|
||
```
|
||
|
||
Would be transformed into these properties:
|
||
|
||
```text
|
||
servers=dev.bar.com,foo.bar.com
|
||
servers[0]=dev.bar.com
|
||
servers[1]=foo.bar.com
|
||
```
|
||
|
||
### Exposing YAML as properties in the Spring Environment.
|
||
The `YamlPropertySourceLoader` class can be used to expose YAML as a `PropertySource`
|
||
in the Spring `Environment`. This allows you to the familiar `@Value` with placeholders
|
||
syntax to access YAML properties.
|
||
|
||
You can also specify multiple profile-specific YAML document in a single file by
|
||
by using a `spring.profiles` key to indicate when the document applies. For example:
|
||
|
||
```yaml
|
||
server:
|
||
address: 192.168.1.100
|
||
---
|
||
spring:
|
||
profiles: production
|
||
server:
|
||
address: 192.168.1.120
|
||
```
|
||
|
||
|
||
## Typesafe Configuration Properties
|
||
Use the `@Value("${property}")` annotation to inject configuration properties can
|
||
sometimes be cumbersome, especially if you are working with multiple properties or
|
||
your data is hierarchical in nature. Spring Boot provides an alternative method
|
||
of working with properties that allows strongly typed beans to govern and validate
|
||
the configuration of your application. For example:
|
||
|
||
```java
|
||
@Component
|
||
@ConfigurationProperties(name="connection")
|
||
public class ConnectionSettings {
|
||
|
||
private String username;
|
||
|
||
private InetAddress remoteAddress;
|
||
|
||
// ... getters and setters
|
||
|
||
}
|
||
```
|
||
|
||
When the `@EnableConfigurationProperties` annotation is applied to your `@Configuration`,
|
||
any beans annotated with `@ConfigurationProperties` will automatically be configured
|
||
from the `Environment` properties. This style of configuration works particularly well
|
||
with the `SpringApplication` external YAML configuration:
|
||
|
||
```yaml
|
||
# application.yml
|
||
|
||
connection:
|
||
username: admin
|
||
remoteAddress: 192.168.1.1
|
||
|
||
# additional configuration as required
|
||
```
|
||
|
||
To work with `@ConfigurationProperties` beans you can just inject them in the same way
|
||
as any other bean.
|
||
|
||
```java
|
||
@Service
|
||
public class MyService {
|
||
|
||
@Autowired
|
||
private ConnectionSettings connection;
|
||
|
||
//...
|
||
|
||
@PostConstruct
|
||
public void openConnection() {
|
||
Server server = new Server();
|
||
this.connection.configure(server);
|
||
}
|
||
}
|
||
```
|
||
|
||
It is also possible to shortcut the registration of `@ConfigurationProperties` bean
|
||
definitions by simply listing the properties classes directly in the
|
||
`@EnableConfigurationProperties` annotation:
|
||
|
||
```java
|
||
@Configuration
|
||
@EnableConfigurationProperties(ConnectionSettings.class)
|
||
public class MyConfiguration {
|
||
}
|
||
```
|
||
|
||
### Relaxed binding
|
||
Spring Boot uses some relaxed rules for binding `Environment` properties to
|
||
`@ConfigurationProperties` beans, so there doesn't need to be an exact match between
|
||
the `Environment` property name and the bean property name. Common examples where this
|
||
is useful include underscore separated (e.g. `context_path` binds to `contextPath`), and
|
||
capitalized (e.g. `PORT` binds to `port`) environment properties.
|
||
|
||
Spring will attempt to coerce the external application properties to the right type when
|
||
it binds to the `@ConfigurationProperties` beans. If you need custom type conversion you
|
||
can provide a `ConversionService` bean (with bean id `conversionService`) or custom
|
||
property editors (via a `CustomEditorConfigurer` bean).
|
||
|
||
### @ConfigurationProperties Validation
|
||
Spring Boot will attempt to validate external configuration, by default using JSR-303
|
||
(if it is on the classpath). You can simply add JSR-303 `javax.valididation` constraint
|
||
annotations to your `@ConfigurationProperties` class:
|
||
|
||
```java
|
||
@Component
|
||
@ConfigurationProperties(name="connection")
|
||
public class ConnectionSettings {
|
||
|
||
@NotNull
|
||
private InetAddress remoteAddress;
|
||
|
||
// ... getters and setters
|
||
|
||
}
|
||
```
|
||
|
||
You can also add a custom Spring `Validator` by creating a bean definition called
|
||
`configurationPropertiesValidator`.
|
||
|
||
### Using Project Lombok
|
||
You can safely use [Project Lombok](http://projectlombok.org) to generate getters and
|
||
setters for your `@ConfigurationProperties`. Refer to the documentation on the Lombok
|
||
for how to enable it in your compiler or IDE.
|
||
|
||
### External EmbeddedServletContainerFactory configuration
|
||
Spring Boot includes a `@ConfigurationProperties` annotated class called
|
||
`ServerProperties` that can be used to configure the `EmbeddedServletContainerFactory`.
|
||
|
||
When registered as a bean, the `ServerProperties` can be used to specify:
|
||
|
||
* The port that the application listens on for its endpoints
|
||
(`server.port` defaults to `8080`)
|
||
* The address that the application endpoints are available on
|
||
(`server.address` defaults to all local addresses, making it available to connections
|
||
from all clients).
|
||
* The context root of the application endpoints (`server.context_path`
|
||
defaults to '/')
|
||
|
||
If you are using Tomcat as you embedded container then, in addition to the
|
||
generic `ServerProperties`, you can also bind `server.tomcat.*` properties
|
||
to specify:
|
||
|
||
* The Tomcat access log pattern (`server.tomcat.accessLogPattern`)
|
||
* The remote IP and protocol headers (`server.tomcat.protocolHeader`,
|
||
`server.tomcat.remoteIpHeader`)
|
||
* The Tomcat `base directory` (`server.tomcat.basedir`)
|
||
|
||
## Customizing Logging
|
||
Spring Boot uses [Commons Logging](commons.apache.org/logging/) for all internal logging,
|
||
but leaves the underlying log implementation open. Default configurations are provided for
|
||
[Java Util Logging](http://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html),
|
||
[Log4J](http://logging.apache.org/log4j/) and [Logback](http://logback.qos.ch/).
|
||
In each case there is console output and file output (rotating, 10MB file size).
|
||
|
||
The various logging systems can be activated by including the appropriate libraries on
|
||
the classpath, and further customized by supported by providing a suitable configuration
|
||
file in the root of the classpath, or in a location specified by the Spring `Environment`
|
||
property `logging.config`.
|
||
|
||
Depending on your logging system, the following files will be loaded:
|
||
|
||
|Logging System|Customization |
|
||
|--------------|-------------------------------|
|
||
|Logback | logback.xml |
|
||
|Log4j | log4j.properties or log4j.xml |
|
||
|JDK | logging.properties |
|
||
|
||
|
||
To help with the customization some other properties are transferred from the Spring
|
||
`Environment` to System properties:
|
||
|
||
|Environment |System Property |Comments |
|
||
|-------------|----------------|---------------------------------------------------------------------------|
|
||
|logging.file |LOG_FILE | Used in default log configuration if defined |
|
||
|logging.path |LOG_PATH | Used in default log configuration if defined |
|
||
|PID |PID | The current process ID is discovered if possible and not already provided |
|
||
|
||
All the logging systems supported can consult System properties when parsing their
|
||
configuration files. See the default configurations in `spring-boot.jar` for examples.
|
||
|
||
## Cloud Foundry Support
|
||
When a `SpringApplication` is deployed to [Cloud Foundry](http://www.cloudfoundry.com/)
|
||
appropriate meta-data will be exposed as `Environemnt` properties. All Cloud Foundry
|
||
properties are prefixed `vcap.` You can use vcap properties to access application
|
||
information (such as the public URL of the application) and service information (such
|
||
as database credentials). See `ApplicationContextInitializer` Javdoc for complete details.
|
||
|
||
## Further Reading
|
||
For more information about any of the classes or interfaces discussed in the document
|
||
please refer to the extensive project Javadoc. If looking to reduce the amount of
|
||
configuration required for your application you should consider
|
||
[spring-boot-autoconfigure](../spring-boot-autoconfigure/README.md). For operational
|
||
concerns see [spring-boot-actuator](../spring-boot-actuator/README.md). For details on
|
||
how to package your application into a single executable JAR file take a look at
|
||
[spring-boot-loader](../spring-boot-loader/README.md).
|
||
|