Enhance some docs and add content to READMEs
Dave Syer
11 years ago
parent
90c942387f
commit
944fd4f4b8
@ -1 +1,156 @@
|
|||||||
# Spring Bootstrap
|
# Spring Bootstrap
|
||||||
|
|
||||||
|
Spring Bootstrap provides features for the other parts of Spring
|
||||||
|
Zero. It is relatively unopinionated and therefore usable as a
|
||||||
|
standalone library for anyone whose tastes diverge from ours.
|
||||||
|
|
||||||
|
|Feature |Implementation |Notes |
|
||||||
|
|---|---|---|
|
||||||
|
|Launch Spring from Java main |SpringApplication | Plenty of convenience methods and customization opportunities |
|
||||||
|
|Server |Tomcat or Jetty | |
|
||||||
|
|Logging |Logback, Log4j or JDK | Sensible defaults configurations. |
|
||||||
|
|Externalized configuration | Properties or YAML | Support for Spring profiles. Bind automatically to @Bean. |
|
||||||
|
|
||||||
|
For a quick introduction and to get started quickly with a new
|
||||||
|
project, carry on reading. For more in depth coverage of the features
|
||||||
|
of Spring Zero Actuator, go to the [Feature Guide](docs/Features.md).
|
||||||
|
|
||||||
|
# Getting Started
|
||||||
|
|
||||||
|
You will need Java (6 at least) and a build tool (Maven is what we use
|
||||||
|
below, but you are more than welcome to use gradle). These can be
|
||||||
|
downloaded or installed easily in most operating systems. For Ubuntu:
|
||||||
|
|
||||||
|
$ sudo apt-get install openjdk-6-jdk maven
|
||||||
|
|
||||||
|
<!--FIXME: short instructions for Mac.-->
|
||||||
|
|
||||||
|
## A basic project
|
||||||
|
|
||||||
|
If you are using Maven create a really simple `pom.xml` with 2 dependencies:
|
||||||
|
|
||||||
|
`pom.xml`
|
||||||
|
|
||||||
|
```
|
||||||
|
<project>
|
||||||
|
<modelVersion>4.0.0</modelVersion>
|
||||||
|
<groupId>com.mycompany</groupId>
|
||||||
|
<artifactId>myproject</artifactId>
|
||||||
|
<version>1.0.0-SNAPSHOT</version>
|
||||||
|
<packaging>jar</packaging>
|
||||||
|
<properties>
|
||||||
|
<start-class>com.mycompany.Application</start-class>
|
||||||
|
</properties>
|
||||||
|
<parent>
|
||||||
|
<groupId>org.springframework.zero</groupId>
|
||||||
|
<artifactId>spring-starter-parent</artifactId>
|
||||||
|
<version>{{project.version}}</version>
|
||||||
|
</parent>
|
||||||
|
<dependencies>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.springframework.zero</groupId>
|
||||||
|
<artifactId>spring-starter</artifactId>
|
||||||
|
</dependency>
|
||||||
|
</dependencies>
|
||||||
|
<build>
|
||||||
|
<plugins>
|
||||||
|
<plugin>
|
||||||
|
<groupId>org.springframework.zero</groupId>
|
||||||
|
<artifactId>spring-package-maven-plugin</artifactId>
|
||||||
|
</plugin>
|
||||||
|
</plugins>
|
||||||
|
</build>
|
||||||
|
</project>
|
||||||
|
```
|
||||||
|
|
||||||
|
If you like Gradle, that's fine, and you will know what to do with
|
||||||
|
those dependencies. The one dependency adds Spring Zero auto
|
||||||
|
configuration and the Tomcat container to your application. If you
|
||||||
|
prefer Jetty you can just add the embedded Jetty jars to your
|
||||||
|
classpath instead of Tomcat.
|
||||||
|
|
||||||
|
Now write a simple main class
|
||||||
|
|
||||||
|
`Application.java`
|
||||||
|
```
|
||||||
|
package com.mycompany;
|
||||||
|
|
||||||
|
import org.springframework.bootstrap.SpringApplication;
|
||||||
|
import org.springframework.context.annotation.Configuration;
|
||||||
|
|
||||||
|
@Configuration
|
||||||
|
public class Application {
|
||||||
|
|
||||||
|
public static void main(String[] args) {
|
||||||
|
SpringApplication.run(Application.class, args);
|
||||||
|
}
|
||||||
|
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
You should be able to run it already:
|
||||||
|
|
||||||
|
$ mvn package
|
||||||
|
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar
|
||||||
|
|
||||||
|
. ____ _ __ _ _
|
||||||
|
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
|
||||||
|
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
|
||||||
|
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
|
||||||
|
' |____| .__|_| |_|_| |_\__, | / / / /
|
||||||
|
=========|_|==============|___/=/_/_/_/
|
||||||
|
Spring Bootstrap
|
||||||
|
|
||||||
|
2013-07-19 17:13:51.673 INFO 18937 --- [ main] com.mycompany.Application ...
|
||||||
|
... <logs showing application starting up>
|
||||||
|
|
||||||
|
It doesn't do anything yet, but that's because all we did is start a
|
||||||
|
Spring `ApplicationContext` and let it close when the JVM stopped.
|
||||||
|
|
||||||
|
To make it do something a little bit more interesting you could bind
|
||||||
|
some command line arguments to the application:
|
||||||
|
|
||||||
|
`Application.java`
|
||||||
|
```
|
||||||
|
@Configuration
|
||||||
|
@ConfigurationProperties
|
||||||
|
@EnableConfigurationProperties
|
||||||
|
public class Application {
|
||||||
|
|
||||||
|
private String message;
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void run(String... args) throws Exception {
|
||||||
|
System.err.println(message);
|
||||||
|
}
|
||||||
|
|
||||||
|
public static void main(String[] args) {
|
||||||
|
SpringApplication.run(Application.class, args);
|
||||||
|
}
|
||||||
|
|
||||||
|
public String getMessage() {
|
||||||
|
return message;
|
||||||
|
}
|
||||||
|
|
||||||
|
public void setMessage(String message) {
|
||||||
|
this.message = message;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `@ConfigurationProperties` annotation binds the Spring
|
||||||
|
`Environment` (including command line arguments) to the `Application`
|
||||||
|
instance, and `CommandLineRunner` is a marker interface for anything
|
||||||
|
you want to be executed after the content is started. So run it
|
||||||
|
again and you will see the message:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ mvn package
|
||||||
|
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar --message="Hello World"
|
||||||
|
...
|
||||||
|
Hello World
|
||||||
|
```
|
||||||
|
|
||||||
|
To add more features, add some `@Bean` definitions to your
|
||||||
|
`Application` class, and read more in the
|
||||||
|
[Feature Guide](docs/Features.md).
|
||||||
|
|||||||
@ -0,0 +1,262 @@
|
|||||||
|
# Spring Bootstrap Feature Guide
|
||||||
|
|
||||||
|
Here are some (most, hopefully all) the features of Spring Bootstrap
|
||||||
|
with some commentary to help you start using them.
|
||||||
|
|
||||||
|
## Commandline Arguments
|
||||||
|
|
||||||
|
Commandline arguments are passed on to any `CommandLineRunner` beans
|
||||||
|
found in the application. Option arguments (starting with `--`,
|
||||||
|
e.g. `--server.port=9000`) are converted to a `PropertySource` and
|
||||||
|
added to the Spring `Environment` with first priority (they always
|
||||||
|
take precedence and override 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.
|
||||||
|
|
||||||
|
@Component
|
||||||
|
public class MyService {
|
||||||
|
@Value("${app.message:Hello World}")
|
||||||
|
private String message;
|
||||||
|
...
|
||||||
|
}
|
||||||
|
|
||||||
|
The default value comes after the first colon (":").
|
||||||
|
|
||||||
|
## Externalized Configuration
|
||||||
|
|
||||||
|
In addition to command line option arguments, Spring Bootstrap will
|
||||||
|
pick up a file called `application.properties` in the root of your
|
||||||
|
classpath (if there is one) and add those properties to the Spring
|
||||||
|
`Environment`. The search path for `application.properties` is
|
||||||
|
actually, 1) root or classpath, 2) current directory, 3) `/config`
|
||||||
|
package in classpath, 4) `/config` subdir of current directory. The
|
||||||
|
list is ordered by decreasing precedence (so properties can be
|
||||||
|
overridden by others with the same name defined in later locations).
|
||||||
|
|
||||||
|
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), e.g.
|
||||||
|
|
||||||
|
app.name: MyApp
|
||||||
|
app.description: ${app.name} is a Cool New App
|
||||||
|
|
||||||
|
Spring Bootstrap also binds the properties to any bean in your
|
||||||
|
application context whose type is `@ConfigurationProperties`. The
|
||||||
|
Actuator provides some of those beans out of the box, so you can
|
||||||
|
easily customize server and management properties (ports etc.),
|
||||||
|
endpoint locations and logging. See below for more detail, or inspect
|
||||||
|
the `*Properties` types in the Actuator jar.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
Spring Bootstap takes it a stage further. If you include in your
|
||||||
|
`application.properties` a value for a property named
|
||||||
|
`spring.active.profiles` then those profiles will be active by
|
||||||
|
default. E.g.
|
||||||
|
|
||||||
|
spring.active.profiles: dev,hsqldb
|
||||||
|
|
||||||
|
## Profile-dependent configuration
|
||||||
|
|
||||||
|
Spring Bootstrap loads additional properties files if there are active
|
||||||
|
profiles using a naming convention `application-{profile}.properties`.
|
||||||
|
Property values from those files override trhe default ones.
|
||||||
|
|
||||||
|
## Custom Typesafe Externalized Configuration
|
||||||
|
|
||||||
|
If you want a strongly typed bean (or beans) to govern and validate
|
||||||
|
the configuration of your application beyond the built in properties,
|
||||||
|
all you need to do is create a `@ConfigurationProperties` class, e.g.
|
||||||
|
|
||||||
|
@ConfigurationProperties(name="my")
|
||||||
|
public class MyProperties {
|
||||||
|
}
|
||||||
|
|
||||||
|
and declare one either explicitly (with `@Bean`) or implicitly by
|
||||||
|
adding
|
||||||
|
|
||||||
|
@EnableConfigurationProperties(MyProperties.class)
|
||||||
|
|
||||||
|
to one of your `@Configuration` (or `@Component`) classes. Then you can
|
||||||
|
|
||||||
|
@Autowired
|
||||||
|
private MyProperties configuration = new MyProperties();
|
||||||
|
|
||||||
|
in any of your component classes to grab that configuration and use it.
|
||||||
|
|
||||||
|
Spring Bootstrap 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).
|
||||||
|
|
||||||
|
Spring will also validate the external configuration, by default using
|
||||||
|
JSR-303 if it is on the classpath. So you can add annotations from
|
||||||
|
that specification (or its implementations) to your custom properties,
|
||||||
|
e.g.
|
||||||
|
|
||||||
|
@ConfigurationProperties(name="my")
|
||||||
|
public class MyProperties {
|
||||||
|
@NotNull
|
||||||
|
private String name;
|
||||||
|
// .. 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.
|
||||||
|
|
||||||
|
## Using YAML instead of Properties
|
||||||
|
|
||||||
|
YAML is a superset of JSON, and as such is a very convenient format
|
||||||
|
for specifying hierarchical configuration data, such as that supported
|
||||||
|
by Spring Actuator. If you prefer to use
|
||||||
|
[YAML](http://yaml.org) instead of Properties files you just need to
|
||||||
|
include a file called `application.yml` in the root of your classpath
|
||||||
|
|
||||||
|
You can if you like add profile specific YAML files
|
||||||
|
(`application-${profile}.yml`), but a nicer alternative is to use YAML
|
||||||
|
documents inside `application.yml`, with profile-specific documents
|
||||||
|
containing a `spring.profiles` key. For example
|
||||||
|
|
||||||
|
server:
|
||||||
|
port: 8080
|
||||||
|
management:
|
||||||
|
port: 8080
|
||||||
|
address: 0.0.0.0
|
||||||
|
---
|
||||||
|
spring:
|
||||||
|
profiles: prod
|
||||||
|
management:
|
||||||
|
port: 8081
|
||||||
|
address: 10.2.68.12
|
||||||
|
|
||||||
|
## Customizing the location of the External Configuration
|
||||||
|
|
||||||
|
If you don't like `application.properties` or `application.yml` as the
|
||||||
|
configuration file location you can switch to another location by
|
||||||
|
specifying the `spring.config.name` (default `application`) or the
|
||||||
|
`spring.config.location` as environment properties, e.g. if launching
|
||||||
|
a jar which wraps `SpringApplication`:
|
||||||
|
|
||||||
|
$ java -jar myproject.jar --spring.config.name=myproject
|
||||||
|
|
||||||
|
## Providing Defaults for Externalized Configuration
|
||||||
|
|
||||||
|
For `@ConfigurationProperties` beans that are provided by the
|
||||||
|
framework itself you can always change the values that are bound to it
|
||||||
|
by changing `application.properties`. But it is sometimes also useful
|
||||||
|
to change the default values imperatively in Java, so get more control
|
||||||
|
over the process. You can do this by declaring a bean of the same
|
||||||
|
type in your application context, e.g. for the server properties:
|
||||||
|
|
||||||
|
@Bean
|
||||||
|
public ServerProperties serverProperties() {
|
||||||
|
ServerProperties server = new ServerProperties();
|
||||||
|
server.setPort(8888);
|
||||||
|
return server;
|
||||||
|
}
|
||||||
|
|
||||||
|
## Server Configuration
|
||||||
|
|
||||||
|
The `ServerProperties` are bound to application properties, and
|
||||||
|
can be used to specify
|
||||||
|
|
||||||
|
* The port that the application listens on for the 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 "/")
|
||||||
|
|
||||||
|
## Tomcat Container Configuration
|
||||||
|
|
||||||
|
If you want to use Tomcat as an embedded container include at least
|
||||||
|
`org.apache.tomcat.embed:tomcat-embed-core` and one of the
|
||||||
|
`org.apache.tomcat.embed:tomcat-embed-logging-*` libraries (depending
|
||||||
|
on the logging system you are using). Then, in addition to the
|
||||||
|
generic `ServerProperties`, you can also bind `server.tomcat.*`
|
||||||
|
properties in the application properties (see
|
||||||
|
`ServerProperties.Tomcat`).
|
||||||
|
|
||||||
|
* To enable the Tomcat access log valve (very common in production environments)
|
||||||
|
|
||||||
|
More fine-grained control of the Tomcat container is available if you
|
||||||
|
need it. Instead of letting Spring Actuator create the container for
|
||||||
|
you, just create a bean of type
|
||||||
|
`TomcatEmbeddedServletContainerFactory` and override one of its
|
||||||
|
methods, or inject some customizations, e.g.
|
||||||
|
|
||||||
|
@Configuration
|
||||||
|
public class MyContainerConfiguration {
|
||||||
|
@Bean
|
||||||
|
public TomcatEmbeddedServletContainerFactory tomcatEmbeddedContainerFactory() {
|
||||||
|
TomcatEmbeddedServletContainerFactory factory = new TomcatEmbeddedServletContainerFactory();
|
||||||
|
factory.setConnector(new Connector("AJP/1.3"));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
(the default connector uses the `Http11NioProtocol` so the example if
|
||||||
|
overriding that behaviour).
|
||||||
|
|
||||||
|
## Customizing Logging
|
||||||
|
|
||||||
|
Spring Bootstrap uses Commons Logging for logging, but leaves the
|
||||||
|
implementation open. A default configuration file is provided for
|
||||||
|
logback, and also for log4j and JDK logging. In each case there is
|
||||||
|
console output and file output (rotating, 10MB file size).
|
||||||
|
|
||||||
|
The various logging systems can be activated by including the right
|
||||||
|
libraries on the classpath, and further customized by providing a
|
||||||
|
native configuration file in the root of the classpath, or in a
|
||||||
|
location specified by the Spring `Environment` property
|
||||||
|
`logging.config`.
|
||||||
|
|
||||||
|
|Logger|Activation |Customization |
|
||||||
|
|---|---|---|
|
||||||
|
|JDK |slf4j-jdk14 | logging.properties |
|
||||||
|
|Logback |logback | logback.xml |
|
||||||
|
|Log4j |slfj4-log4j12, log4j | log4j.properties or log4j.xml |
|
||||||
|
|
||||||
|
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-bootstrap.jar` for examples.
|
||||||
|
|
||||||
|
## Application Context Initializers
|
||||||
|
|
||||||
|
To add additional application context initializers to the bootstrap
|
||||||
|
startup process, add a comma-delimited list of class names to the
|
||||||
|
`Environment` property `context.initializer.classes` (can be specified
|
||||||
|
via `application.properties`).
|
||||||
|
|
||||||
Loading…
Reference in New Issue