Enhance some docs and add content to READMEs
Dave Syer
11 years ago
parent
90c942387f
commit
944fd4f4b8
@ -1 +1,156 @@
|
||||
# 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