root
/
spring-boot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

Remove duplicate documentation

Browse Source 
Remove README files that have been since been migrated to the reference
documentation. Also updated remaining markdown files to asciidoctor to
save having a mix of different formats.

Fixed gh-503
pull/505/head
Phillip Webb 11 years ago
parent d0275b4734
commit c5ee3c7eba
24 changed files with 287 additions and 4418 deletions
Show Stats Download Patch File Download Diff File

107
CONTRIBUTING.md → CONTRIBUTING.adoc
Unescape Escape View File

@ -1,58 +1,68 @@
# Contributing to Spring Boot
= Contributing to Spring Boot
Spring Boot is released under the non-restrictive Apache 2.0 license. If you would like
to contribute something, or simply want to hack on the code this document should help
you get started.
## Sign the Contributor License Agreement
== Sign the Contributor License Agreement
Before we accept a non-trivial patch or pull request we will need you to sign the
[contributor's agreement](https://support.springsource.com/spring_committer_signup).
Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we
can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join
the core team, and given the ability to merge pull requests.
## Code Conventions and Housekeeping
None of these is essential for a pull request, but they will all help. They can also be added after the original pull
request but before a merge.
* Use the Spring Framework code format conventions. Import `eclipse-code-formatter.xml` from the `eclipse` folder of the project
if you are using Eclipse. If using IntelliJ, copy `spring-intellij-code-style.xml` to `~/.IntelliJIdea*/config/codestyles`
and select spring-intellij-code-style from Settings -> Code Styles.
* Make sure all new .java files to have a simple Javadoc class comment with at least an @author tag identifying you, and
preferably at least a paragraph on what the class is for.
* Add the ASF license header comment to all new .java files (copy from existing files in the project)
* Add yourself as an @author to the .java files that you modify substantially (more than cosmetic changes).
https://support.springsource.com/spring_committer_signup[contributor's agreement].
Signing the contributor's agreement does not grant anyone commit rights to the main
repository, but it does mean that we can accept your contributions, and you will get an
author credit if we do. Active contributors might be asked to join the core team, and
given the ability to merge pull requests.
== Code Conventions and Housekeeping
None of these is essential for a pull request, but they will all help. They can also be
added after the original pull request but before a merge.
* Use the Spring Framework code format conventions. Import `eclipse-code-formatter.xml`
from the `eclipse` folder of the project if you are using Eclipse. If using IntelliJ,
copy `spring-intellij-code-style.xml` to `~/.IntelliJIdea*/config/codestyles` and select
spring-intellij-code-style from Settings -> Code Styles.
* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
`@author` tag identifying you, and preferably at least a paragraph on what the class is
for.
* Add the ASF license header comment to all new `.java` files (copy from existing files
in the project)
* Add yourself as an `@author` to the .java files that you modify substantially (more
than cosmetic changes).
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
* A few unit tests would help a lot as well - someone has to do it.
* If no-one else is using your branch, please rebase it against the current master (or other target branch in the main project).
* A few unit tests would help a lot as well -- someone has to do it.
* If no-one else is using your branch, please rebase it against the current master (or
other target branch in the main project).
## Working with the code
== Working with the code
If you don't have an IDE preference we would recommend that you use
[Spring Tools Suite](http://www.springsource.com/developer/sts) or
[Eclipse](http://eclipse.org) when working with the code. We use the
[m2eclipe](http://eclipse.org/m2e/) eclipse plugin for maven support. Other IDEs
and tools should also work without issue.
http://www.springsource.com/developer/sts[Spring Tools Suite] or
http://eclipse.org[Eclipse] when working with the code. We use the
http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools
should also work without issue.
### Building from source
=== Building from source
To build the source you will need to install
[Apache Maven](http://maven.apache.org/run-maven/index.html) v3.0 or above.
http://maven.apache.org/run-maven/index.html[Apache Maven] v3.0 or above.
#### Default build
==== Default build
The project can be built from the root directory using the standard maven command:
[indent=0]
----
$ mvn clean install
----
> **NOTE:** You may need to increase the amount of memory available to Maven by setting
> a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m`
NOTE: You may need to increase the amount of memory available to Maven by setting
a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m`
If you are rebuilding often, you might also want to skip the tests until you are ready
to submit a pull request:
[indent=0]
----
$ mvn clean install -DskipTests
----
#### Full Build
==== Full Build
Multi-module Maven builds cannot directly include maven plugins that are part of the
reactor unless they have previously been built. Unfortunately this restriction causes
some compilations for Spring Boot as we include a maven plugin and use it within the
@ -71,24 +81,30 @@ can be referenced during the full build. It also generates a `settings.xml` file
enables a `snapshot`, `milestone` or `release` profiles based on the version being
build. To prepare the build, from the root directory use:
[indent=0]
----
$ mvn -P snapshot,prepare install
----
> **NOTE:** You may notice that preparing the build also changes the
> `spring-boot-starter-parent` POM. This is required for our release process to work
> correctly.
NOTE: You may notice that preparing the build also changes the
`spring-boot-starter-parent` POM. This is required for our release process to work
correctly.
2) Run the full build
Once the build has been prepared, you can run a full build using the following commands:
[indent=0]
----
$ cd spring-boot-full-build
$ mvn -s ../settings.xml -P full clean install
----
We generate more artifacts when running the full build (such as Javadoc jars), so you
may find the process a little slower than the standard build.
### Importing into eclipse with m2eclipse
We recommend the [m2eclipe](http://eclipse.org/m2e/) eclipse plugin when working with
=== Importing into eclipse with m2eclipse
We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
marketplace".
@ -98,30 +114,33 @@ work with m2eclipse, we provide an additional eclipse plugin that you can instal
* Select `Install new software` from the `help` menu
* Click `Add...` to add a new repository
* Click the `Archive...` button
* Select `org.eclipse.m2e.maveneclipse.site-0.0.1-SNAPSHOT-site.zip`
from the `eclipse` folder in this checkout
* Select `org.eclipse.m2e.maveneclipse.site-0.0.1-SNAPSHOT-site.zip` from the `eclipse`
folder in this checkout
* Install "Maven Integration for the maven-eclipse-plugin"
_NOTE: This plugin is optional. Projects can be imported without the plugin, your code
NOTE: This plugin is optional. Projects can be imported without the plugin, your code
changes just won't be automatically formatted._
With the requisite eclipse plugins installed you can select
`import existing maven projects` from the `file` menu to import the code. You will
need to import the root `spring-boot` pom and the `spring-boot-samples` pom separately.
### Importing into eclipse without m2eclipse
=== Importing into eclipse without m2eclipse
If you prefer not to use m2eclipse you can generate eclipse project meta-data using the
following command:
[indent=0]
----
$ mvn eclipse:eclipse
----
The generated eclipse projects can be imported by selecting `import existing projects`
from the `file` menu.
### Importing into other IDEs
=== Importing into other IDEs
Maven is well supported by most Java IDEs. Refer to you vendor documentation.
### Integration tests
== Integration tests
The sample application are used as integration tests during the build (when you
`mvn install`). Due to the fact that they make use of the `spring-boot-maven-plugin`
they cannot be called directly, and so instead are launched via the

214
README.adoc
Unescape Escape View File

@ -0,0 +1,214 @@
= Spring Boot image:https://travis-ci.org/spring-projects/spring-boot.png?branch=master["Build Status", link="https://travis-ci.org/spring-projects/spring-boot"]
:docs: http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference
Spring Boot makes it easy to create Spring-powered, production-grade applications and
services with absolute minimum fuss. It takes an opinionated view of the Spring platform
so that new and existing users can quickly get to the bits they need.
You can use Spring Boot to create stand-alone Java applications that can be started using
`java -jar` or more traditional WAR deployments. We also provide a command line tool
that runs spring scripts.
Our primary goals are:
* Provide a radically faster and widely accessible getting started experience for all
Spring development
* Be opinionated out of the box, but get out of the way quickly as requirements start to
diverge from the defaults
* Provide a range of non-functional features that are common to large classes of projects
(e.g. embedded servers, security, metrics, health checks, externalized configuration)
* Absolutely no code generation and no requirement for XML configuration
== Installation and Getting Started
The {docs}/htmlsingle/[reference documentation] includes detailed
{docs}/htmlsingle/#getting-started-installing-spring-boot[installation instructions]
as well as a comprehensive {docs}/htmlsingle/#getting-started-first-application[``getting
started''] guide. Documentation is published in {docs}/htmlsingle/[HTML],
{docs}/pdf/spring-boot-reference.pdf[PDF] and {docs}/epub/spring-boot-reference.epub[EPUB]
formats.
Here is a quick teaser of a Spring Boot application:
[source,java,indent=0]
----
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.stereotype.*;
import org.springframework.web.bind.annotation.*;
@Controller
@EnableAutoConfiguration
public class Example {
@RequestMapping("/")
@ResponseBody
String home() {
return "Hello World!";
}
public static void main(String[] args) throws Exception {
SpringApplication.run(Example.class, args);
}
}
----
== Getting help
Having trouble with Spring Boot, We'd like to help!
* Check the {docs}/htmlsingle/[reference documentation], especially the
{docs}/htmlsingle/#howto[How-to's] -- they provide solutions to the most common
questions.
* Learn the Spring basics -- Spring Boot is builds on many other Spring projects, check
the http://spring.io[spring.io] web-site for a wealth of reference documentation. If
you are just starting out with Spring, try one of the http://spring.io/guides[guides].
* Ask a questions - we monitor http://stackoverflow.com[stackoverflow.com] for questions
tagged with http://stackoverflow.com/tags/spring-boot[`spring-boot`].
* Report bugs with Spring Boot at https://github.com/spring-projects/spring-boot/issues.
== Building from Source
You don't need to build from source to use Spring Boot (binaries in
http://repo.spring.io[repo.spring.io], but if you want to try out the latest and greatest,
Spring Boot can be http://maven.apache.org/run-maven/index.html[built with maven]
v3.0.5 or above.
[indent=0]
----
$ mvn clean install
----
NOTE: You may need to increase the amount of memory available to Maven by setting
a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m`
_Also see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] if you wish to submit pull requests,
and in particular please fill out the
https://support.springsource.com/spring_committer_signup[Contributor's Agreement]
before your first change however trivial. (Or if you filed such an agreement already for
another project just mention that in your pull request.)_
== Modules
There are a number of modules in Spring Boot, here is a quick overview:
=== spring-boot
The main library providing features that support the other parts of Spring Boot,
these include:
* The `SpringApplication` class, providing static convenience methods that make it easy
to write a stand-alone Spring Application. Its sole job is to create and refresh an
appropriate Spring `ApplicationContext`
* Embedded web applications with a choice of container (Tomcat or Jetty for now)
* First class externalized configuration support
* Convenience `ApplicationContext` initializers, including support for sensible logging
defaults
=== spring-boot-autoconfigure
Spring Boot can configure large parts of common applications based on the content
of their classpath. A single `@EnableAutoConfiguration` annotation triggers
auto-configuration of the Spring context.
Auto-configuration attempts to deduce which beans a user might need. For example, If
`HSQLDB` is on the classpath, and the user has not configured any database connections,
then they probably want an in-memory database to be defined. Auto-configuration will
always back away as the user starts to define their own beans.
=== spring-boot-starters
Starters are a set of convenient dependency descriptors that you can include in
your application. You get a one-stop-shop for all the Spring and related technology
that you need without having to hunt through sample code and copy paste loads of
dependency descriptors. For example, if you want to get started using Spring and JPA for
database access just include the `spring-boot-starter-data-jpa` dependency in your
project, and you are good to go.
=== spring-boot-cli
The Spring command line application compiles and runs Groovy source, making it super
easy to write the absolute minimum of code to get an application running. Spring CLI
can also watch files, automatically recompiling and restarting when they change.
=== spring-boot-actuator
Spring Boot Actuator provides additional auto-configuration to decorate your application
with features that make it instantly deployable and supportable in production. For
instance if you are writing a JSON web service then it will provide a server, security,
logging, externalized configuration, management endpoints, an audit abstraction, and
more. If you want to switch off the built in features, or extend or replace them, it
makes that really easy as well.
=== spring-boot-loader
Spring Boot Loader provides the secret sauce that allows you to build a single jar file
that can be launched using `java -jar`. Generally you will not need to use
`spring-boot-loader` directly, but instead work with the
link:spring-boot-tools/spring-boot-gradle-plugin[Gradle] or
link:spring-boot-tools/spring-boot-maven-plugin[Maven] plugin.
== Samples
Groovy samples for use with the command line application are available in
link:spring-boot-cli/samples[spring-boot-cli/samples]. To run the CLI samples type
`spring run <sample>.groovy` from samples directory.
Java samples are available in link:spring-boot-samples[spring-boot-samples] and should
be built with maven and run by invoking `java -jar target/<sample>.jar`. The following
java samples are provided:
* link:spring-boot-samples/spring-boot-sample-simple[spring-boot-sample-simple]
-- A simple command line application
* link:spring-boot-samples/spring-boot-sample-tomcat[spring-boot-sample-tomcat]
-- Embedded Tomcat
* link:spring-boot-samples/spring-boot-sample-jetty[spring-boot-sample-jetty]
-- Embedded Jetty
* link:spring-boot-samples/spring-boot-sample-actuator[spring-boot-sample-actuator]
-- Simple REST service with production features
* link:spring-boot-samples/spring-boot-sample-actuator-ui[spring-boot-sample-actuator-ui]
-- A web UI example with production features
* link:spring-boot-samples/spring-boot-sample-web-ui[spring-boot-sample-web-ui]
-- A thymeleaf web application
* link:spring-boot-samples/spring-boot-sample-web-static[spring-boot-sample-web-static]
-- A web application service static files
* link:spring-boot-samples/spring-boot-sample-batch[spring-boot-sample-batch]
-- Define and run a Batch job in a few lines of code
* link:spring-boot-samples/spring-boot-sample-data-jpa[spring-boot-sample-data-jpa]
-- Spring Data JPA + Hibernate + HSQLDB
* link:spring-boot-samples/spring-boot-sample-integration[spring-boot-sample-integration]
-- A spring integration application
* link:spring-boot-samples/spring-boot-sample-profile[spring-boot-sample-profile]
-- example showing Spring's `@profile` support
* link:spring-boot-samples/spring-boot-sample-traditional[spring-boot-sample-traditional]
-- shows more traditional WAR packaging (but also executable using `java -jar`)
* link:spring-boot-samples/spring-boot-sample-xml[spring-boot-sample-xml]
-- Example show how Spring Boot can be mixed with traditional XML configuration (we
generally recommend using Java `@Configuration` whenever possible)
== Guides
The http://spring.io/[spring.io] site contains several guides that show how to use Spring
Boot step-by-step:
* http://spring.io/guides/gs/spring-boot/[Building an Application with Spring Boot] is a
very basic guide that shows you how to create a simple application, run it and add some
management services.
* http://spring.io/guides/gs/actuator-service/[Building a RESTful Web Service with Spring
Boot Actuator] is a guide to creating a REST web service and also shows how the server
can be configured.
* http://spring.io/guides/gs/convert-jar-to-war/[Converting a Spring Boot JAR Application
to a WAR] shows you how to run applications in a web server as a WAR file.

400
README.md
Unescape Escape View File

@ -1,400 +0,0 @@
# Spring Boot [![Build Status](https://travis-ci.org/spring-projects/spring-boot.png?branch=master)](https://travis-ci.org/spring-projects/spring-boot)
Spring Boot makes it easy to create Spring-powered, production-grade applications and
services with absolute minimum fuss. It takes an opinionated view of the Spring platform
so that new and existing users can quickly get to the bits they need.
You can use Spring Boot to create stand-alone Java applications that can be started using
`java -jar` or more traditional WAR deployments. We also provide a command line tool
that runs spring scripts.
Our primary goals are:
* Provide a radically faster and widely accessible getting started experience for all
Spring development
* Be opinionated out of the box, but get out of the way quickly as requirements start to
diverge from the defaults
* Provide a range of non-functional features that are common to large classes of projects
(e.g. embedded servers, security, metrics, health checks, externalized configuration)
* Absolutely no code generation and no requirement for XML configuration
A good place for further reading is the
[compendium of micro HOWTO guides](docs/howto.md) covering many common
use cases.
## Spring Boot CLI
The Spring Boot CLI is a command line tool that can be used if you want to quickly
prototype with Spring. It allows you to run [Groovy](http://groovy.codehaus.org/) scripts,
which means that you have a familiar Java-like syntax, without so much boilerplate code.
You don't need to use the CLI to work with Spring Boot but it's definitely the quickest
way to get a Spring application off the ground.
> **Note:** If you don't want to use the CLI,
> [jump ahead to the Java example](#quick-start-java-example).
### Installing the CLI
You need [Java SDK v1.6](http://www.java.com) or higher to run the command line tool
(there are even some issues with the `1.7.0_25` build of openjdk, so stick to earlier
builds or use `1.6` for preference). You should check your current Java installation
before you begin:
$ java -version
### Manual installation
You can download the Spring CLI distribution from the Spring software repository:
* [spring-boot-cli-1.0.0.RC4-bin.zip](http://repo.spring.io/milestone/org/springframework/boot/spring-boot-cli/1.0.0.RC4/spring-boot-cli-1.0.0.RC4-bin.zip)
* [spring-boot-cli-1.0.0.RC4-bin.tar.gz](http://repo.spring.io/milestone/org/springframework/boot/spring-boot-cli/1.0.0.RC4/spring-boot-cli-1.0.0.RC4-bin.tar.gz)
Cutting edge [snapshot distributions](http://repo.spring.io/snapshot/org/springframework/boot/spring-boot-cli/)
are also available.
Once downloaded, follow the
[INSTALL](spring-boot-cli/src/main/content/INSTALL.txt) instructions
from the unpacked archive. In summary: there is a `spring` script
(`spring.bat` for Windows) in a `bin/` directory in the `.zip` file,
or alternatively you can use `java -jar` with the `.jar` file (the
script helps you to be sure that the classpath is set correctly).
### Installation with GVM
GVM (the Groovy Environment Manager) can be used for managing multiple
versions of verious Groovy and Java binary packages, including Groovy
itself and the Spring Boot CLI. Get `gvm` from
[the gvm home page](http://gvmtool.net) and install Spring Boot with
$ gvm install springboot
$ spring --version
Spring Boot v1.0.0.RC4
> **Note:** If you are developing features for the CLI and want easy access to the version you just built, follow these extra instructions.
$ gvm install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-1.0.0.BUILD-SNAPSHOT-bin/spring-1.0.0.BUILD-SNAPSHOT/
$ gvm use springboot dev
$ spring --version
Spring CLI v1.0.0.BUILD-SNAPSHOT
This will install a local instance of `spring` called the `dev` instance inside your gvm repository. It points at your target build location, so every time you rebuild Spring Boot, `spring` will be up-to-date.
You can see it by doing this:
$ gvm ls springboot
```
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 1.0.0.RC4
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
```
### OSX Homebrew installation
If you are on a Mac and using [homebrew](http://brew.sh/), all you need to do to install
the Spring Boot CLI is:
```
$ brew tap pivotal/tap
$ brew install springboot
```
Homebrew will install `spring` to `/usr/local/bin`. Now you can jump right to a
[quick start example](#quick-start-script-example).
> **Note:** If you don't see the formula, you're installation of brew might be
> out-of-date. Just execute `brew update` and try again.
### Quick start script example
Here's a really simple web application. Create a file called `app.groovy`:
```groovy
@Controller
class ThisWillActuallyRun {
@RequestMapping("/")
@ResponseBody
String home() {
return "Hello World!"
}
}
```
Then run it from a shell:
```
$ spring run app.groovy
```
> **Note:** It will take some time when you first run the application as dependencies
> are downloaded, subsequent runs will be much quicker.
Open [http://localhost:8080](http://localhost:8080) in your favorite web browser and you
should see the following output:
> Hello World!
## Spring Boot with Java
If you don't want to use the command line tool, or you would rather work using Java and
an IDE you can. Here is how you build the same example using Java.
### Quick start Maven POM
You will need to install [Apache Maven](http://maven.apache.org/) v3.0.5 or above to build
this example.
Create a `pom.xml` to import the appropriate Spring Boot starters:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.0.0.RC4</version>
</parent>
<!-- Add typical dependencies for a web application -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<!-- Package as an executable JAR -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
<!-- Allow access to Spring milestones and snapshots -->
<!-- (you don't need this if you are using anything after 1.0.0.RELEASE) -->
<repositories>
<repository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
<repository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</pluginRepository>
</pluginRepositories>
</project>
```
> **Note:** If you prefer [Gradle](http://www.gradle.org) as your build system, we provide
> a [plugin](spring-boot-tools/spring-boot-gradle-plugin/README.md) that can help you
> package an executable JAR.
More detail about the Maven plugin, and how to build a Spring Boot
project with Maven is available in the [starter docs](spring-boot-starters/README.md).
<span id="quick-start-java-example"></span>
### Quick start Java example
Here is the main class for a simple web application (just save the content to
`src/main/java/SampleController.java`):
```java
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.stereotype.*;
import org.springframework.web.bind.annotation.*;
@Controller
@EnableAutoConfiguration
public class SampleController {
@RequestMapping("/")
@ResponseBody
String home() {
return "Hello World!";
}
public static void main(String[] args) throws Exception {
SpringApplication.run(SampleController.class, args);
}
}
```
Other than import statements, the main difference between this
example and the earlier Groovy script is the `main()` method that calls
`SpringApplication` and the `@EnableAutoConfiguration` annotation.
You can run this application by building a `jar` and executing it:
```
$ mvn package
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
```
Open [http://localhost:8080](http://localhost:8080) in your favorite web browser and you
should see the following output:
> Hello World!
## Building Spring Boot from source
You don't need to build from source to use Spring Boot (it's in
[repo.spring.io](http://repo.spring.io)), but if you want to try out the
latest and greatest, Spring Boot can be
[built with maven](http://maven.apache.org/run-maven/index.html) v3.0.5 or above.
$ mvn clean install
> **NOTE:** You may need to increase the amount of memory available to Maven by setting
> a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m`
_Also see [CONTRIBUTING.md](CONTRIBUTING.md) if you wish to submit
pull requests, and in particular please fill out the
[Contributor's Agreement](https://support.springsource.com/spring_committer_signup)
before your first change however trivial. (Or if you filed such an
agreement already for another project just mention that in your pull
request.)_
## Modules
There are a number of modules in Spring Boot, if you want learn more about each one
please refer to the appropriate README.md file:
> **Note:** We are currently still working on documentation for Spring Boot.
### spring-boot
The main library providing features that support the other parts of Spring Boot,
these include:
* The `SpringApplication` class, providing static convenience methods that make it easy
to write a stand-alone Spring Application. Its sole job is to create and refresh an
appropriate Spring `ApplicationContext`
* Embedded web applications with a choice of container (Tomcat or Jetty for now)
* First class externalized configuration support
* Convenience `ApplicationContext` initializers, including support for sensible logging
defaults
_See [spring-boot/README.md](spring-boot/README.md)._
### spring-boot-autoconfigure
Spring Boot can configure large parts of common applications based on the content
of their classpath. A single `@EnableAutoConfiguration` annotation triggers
auto-configuration of the Spring context.
Auto-configuration attempts to deduce which beans a user might need. For example, If
`HSQLDB` is on the classpath, and the user has not configured any database connections,
then they probably want an in-memory database to be defined. Auto-configuration will
always back away as the user starts to define their own beans.
_See [spring-boot-autoconfigure/README.md](spring-boot-autoconfigure/README.md)._
### spring-boot-starters
Starters are a set of convenient dependency descriptors that you can include in
your application. You get a one-stop-shop for all the Spring and related technology
that you need without having to hunt through sample code and copy paste loads of
dependency descriptors. For example, if you want to get started using Spring and JPA for
database access just include the `spring-boot-starter-data-jpa` dependency in your
project, and you are good to go.
_See [spring-boot-starters/README.md](spring-boot-starters/README.md)._
### spring-boot-cli
The Spring command line application compiles and runs Groovy source, making it super
easy to write the absolute minimum of code to get an application running. Spring CLI
can also watch files, automatically recompiling and restarting when they change.
*See [spring-boot-cli/README.md](spring-boot-cli/README.md).*
### spring-boot-actuator
Spring Boot Actuator provides additional auto-configuration to decorate your application
with features that make it instantly deployable and supportable in production. For
instance if you are writing a JSON web service then it will provide a server, security,
logging, externalized configuration, management endpoints, an audit abstraction, and
more. If you want to switch off the built in features, or extend or replace them, it
makes that really easy as well.
_See [spring-boot-actuator/README.md](spring-boot-actuator/README.md)._
### spring-boot-loader
Spring Boot Loader provides the secret sauce that allows you to build a single jar file
that can be launched using `java -jar`. Generally you will not need to use
`spring-boot-loader` directly, but instead work with the
[Gradle](spring-boot-tools/spring-boot-gradle-plugin/README.md) or
[Maven](spring-boot-tools/spring-boot-maven-plugin/README.md) plugin.
_See [spring-boot-loader/README.md](spring-boot-tools/spring-boot-loader/README.md)._
## Samples
Groovy samples for use with the command line application are available in
[spring-boot-cli/samples](spring-boot-cli/samples). To run the CLI samples type
`spring run <sample>.groovy` from samples directory.
Java samples are available in [spring-boot-samples](spring-boot-samples) and should
be built with maven and run by invoking `java -jar target/<sample>.jar`. The following java
samples are provided:
* [spring-boot-sample-simple](spring-boot-samples/spring-boot-sample-simple) -
A simple command line application
* [spring-boot-sample-tomcat](spring-boot-samples/spring-boot-sample-tomcat) -
Embedded Tomcat
* [spring-boot-sample-jetty](spring-boot-samples/spring-boot-sample-jetty) -
Embedded Jetty
* [spring-boot-sample-actuator](spring-boot-samples/spring-boot-sample-actuator) -
Simple REST service with production features
* [spring-boot-sample-actuator-ui](spring-boot-samples/spring-boot-sample-actuator-ui) -
A web UI example with production features
* [spring-boot-sample-web-ui](spring-boot-samples/spring-boot-sample-web-ui) -
A thymeleaf web application
* [spring-boot-sample-web-static](spring-boot-samples/spring-boot-sample-web-static) -
A web application service static files
* [spring-boot-sample-batch](spring-boot-samples/spring-boot-sample-batch) -
Define and run a Batch job in a few lines of code
* [spring-boot-sample-data-jpa](spring-boot-samples/spring-boot-sample-data-jpa) -
Spring Data JPA + Hibernate + HSQLDB
* [spring-boot-sample-integration](spring-boot-samples/spring-boot-sample-integration) -
A spring integration application
* [spring-boot-sample-profile](spring-boot-samples/spring-boot-sample-profile) -
example showing Spring's `@profile` support
* [spring-boot-sample-traditional](spring-boot-samples/spring-boot-sample-traditional) -
shows more traditional WAR packaging
(but also executable using `java -jar`)
* [spring-boot-sample-xml](spring-boot-samples/spring-boot-sample-xml) -
Example show how Spring Boot can be mixed with traditional XML configuration (we
generally recommend using Java `@Configuration` whenever possible)
## Guides
The [spring.io](http://spring.io/) site contains several guides that show how to use Spring Boot step-by-step:
* [Building an Application with Spring
Boot](http://spring.io/guides/gs/spring-boot/) is a very basic guide
that shows you how to create a simple application, run it and add some
management services.
* [Building a RESTful Web Service with Spring Boot Actuator](http://spring.io/guides/gs/actuator-service/)
is a guide to creating a REST web service and also shows how the server can be configured.
* [Converting a Spring Boot JAR Application to a WAR](http://spring.io/guides/gs/convert-jar-to-war/) shows you how to run applications in a
web server as a WAR file.

4
docs/README.adoc
Unescape Escape View File

@ -0,0 +1,4 @@
= NOTE
Documentation can now be found in the `spring-boot-docs` project. This folder will be
removed at a future date.

151
docs/SCRAPBOOK.md
Unescape Escape View File

@ -1,151 +0,0 @@
# Docs without a home as yet :(
|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.
# 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.boot</groupId>
<artifactId>spring-starter-parent</artifactId>
<version>{{project.version}}</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-starter</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</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 Boot.Config 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.boot.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.

105
docs/application.yml
Unescape Escape View File

@ -1,105 +0,0 @@
# Core
spring:
# The name of the application
application.name: myapp
# The name of the main config file, default is application
config.name: application
# Profiles that should be active
profiles.active:
# Configuration for SpringApplication setters
main:
web-environment: true
show-banner:false
log-startup-info: false
# ...
# Server settings (ServerProperties)
server:
port: 8080
address: 127.0.0.1
sessionTimeout: 30
contextPath: /root
# Tomcat specifics
tomcat:
accessLogEnabled: false
protocolHeader: x-forwarded-proto
remoteIpHeader: x-forwarded-for
basedir:
backgroundProcessorDelay: 30 # secs
---
# Auto-Configure
spring:
messages:
basename: messages
batch:
schema: classpath:org/springframework/batch/core/schema-@@platform@@.sql
database:
schema: classpath*:schema-<platform>.sql
platform: all
datasource:
driverClassName
url:
username: sa
password
max-active: 8
max-idle: 8
test-on-borrow
test-on-return
validation-query
jpa:
open-in-view:
show-sql:
database-platform:
generate-ddl:
properties:
hibernate:
naming-strategy:
cache-provider:
ddl-auto:
thymeleaf:
prefix: classpath:/templates/
suffix: .html
mode: HTML5
cache: true
view:
prefix:
suffix:
# actuator
endpoints:
beans:
path: /beans
sensitive: false
dump:
env
health
info
metrics
shutdown
trace
# (ManagementServerProperties)
management:
port:
# (SecurityProperties)
security:
basic:
enabled: true

53
docs/autoconfig.md
Unescape Escape View File

@ -1,53 +0,0 @@
# Spring Boot Auto Configuration Classes
Here is a list of all auto configuration classes provided by Spring
Boot with links to documentation and source code. Remember to also
look at the autoconfig report in your application for more details of
which fetaures are switched on in that specific use case (start the
app with "--debug" or "-Ddebug", or in an Actuator app go to
"/autoconfig").
(Auto-generated from `classpath*:/META-INF/spring.factories`.)
| Configuration Class | Links | Project |
|---|---|---|
| [MessageSourceAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/MessageSourceAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/MessageSourceAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [PropertyPlaceholderAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/PropertyPlaceholderAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/PropertyPlaceholderAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [RabbitAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/amqp/RabbitAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/amqp/RabbitAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [AopAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/aop/AopAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/aop/AopAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [BatchAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/batch/BatchAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/batch/BatchAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [JpaRepositoriesAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/data/JpaRepositoriesAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/data/JpaRepositoriesAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [MongoRepositoriesAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/data/MongoRepositoriesAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/data/MongoRepositoriesAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [MongoTemplateAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/data/MongoTemplateAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/data/MongoTemplateAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [DataSourceAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/jdbc/DataSourceAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/jdbc/DataSourceAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [DataSourceTransactionManagerAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/jdbc/DataSourceTransactionManagerAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/jdbc/DataSourceTransactionManagerAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [JmsTemplateAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/jms/JmsTemplateAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/jms/JmsTemplateAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [JmxAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/jmx/JmxAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/jmx/JmxAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [DeviceResolverAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/mobile/DeviceResolverAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/mobile/DeviceResolverAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [MongoAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/mongo/MongoAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/mongo/MongoAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [HibernateJpaAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/orm/jpa/HibernateJpaAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/orm/jpa/HibernateJpaAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [ReactorAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/reactor/ReactorAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/reactor/ReactorAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [RedisAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/redis/RedisAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/redis/RedisAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [SecurityAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/security/SecurityAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/security/SecurityAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [ThymeleafAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/thymeleaf/ThymeleafAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/thymeleaf/ThymeleafAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [DispatcherServletAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/DispatcherServletAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/web/DispatcherServletAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [EmbeddedServletContainerAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/EmbeddedServletContainerAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/web/EmbeddedServletContainerAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [HttpMessageConvertersAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/HttpMessageConvertersAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/web/HttpMessageConvertersAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [MultipartAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/MultipartAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/web/MultipartAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [ServerPropertiesAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/ServerPropertiesAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/web/ServerPropertiesAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [WebMvcAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/WebMvcAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/web/WebMvcAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [WebSocketAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/websocket/WebSocketAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/autoconfigure/websocket/WebSocketAutoConfiguration.html) | [spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-autoconfigure) |
| [AuditAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/AuditAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/AuditAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [CrshAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/CrshAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/CrshAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [EndpointAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/EndpointAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/EndpointAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [EndpointMBeanExportAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/EndpointMBeanExportAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/EndpointMBeanExportAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [EndpointWebMvcAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/EndpointWebMvcAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/EndpointWebMvcAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [ErrorMvcAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/ErrorMvcAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/ErrorMvcAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [JolokiaAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/JolokiaAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/JolokiaAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [ManagementSecurityAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/ManagementSecurityAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/ManagementSecurityAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [ManagementServerPropertiesAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/ManagementServerPropertiesAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/ManagementServerPropertiesAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [MetricFilterAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/MetricFilterAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/MetricFilterAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [MetricRepositoryAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/MetricRepositoryAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/MetricRepositoryAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [TraceRepositoryAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/TraceRepositoryAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/TraceRepositoryAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |
| [TraceWebFilterAutoConfiguration](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/autoconfigure/TraceWebFilterAutoConfiguration.java) | [javadoc](http://docs.spring.io/spring-boot/docs/1.0.0.RC4/api/org/springframework/boot/actuate/autoconfigure/TraceWebFilterAutoConfiguration.html) | [spring-boot-actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator) |

1336
docs/howto.md
View File

File diff suppressed because it is too large Load Diff

376
spring-boot-actuator/README.md
Unescape Escape View File

@ -1,376 +0,0 @@
# Spring Boot - Actuator
> **Note:** Some of this documentation covers concepts from other modules, it will be
> cleaned up before the final release.
The aim of this project is minimum fuss for getting applications up
and running in production, and in other environments. There is a
strong emphasis on implementing RESTful web services but many features
are more generic than that.
|Feature |Implementation |Notes |
|---|---|---|
|Server |Tomcat or Jetty | Whatever is on the classpath |
|REST |Spring MVC | |
|Security |Spring Security | If on the classpath |
|Logging |Logback, Log4j or JDK | Whatever is on the classpath. Sensible defaults. |
|Database |HSQLDB or H2 | Per classpath, or define a DataSource to override |
|Externalized configuration | Properties or YAML | Support for Spring profiles. Bind automatically to @Bean. |
|Audit | Spring Security and Spring ApplicationEvent |Flexible abstraction with sensible defaults for security events |
|Validation | JSR-303 |If on the classpath |
|Management endpoints | Spring MVC | Health, basic metrics, request tracing, shutdown, thread dumps |
|Error pages | Spring MVC | Sensible defaults based on exception and status code |
|JSON |Jackson 2 | |
|ORM |Spring Data JPA | If on the classpath |
|Batch |Spring Batch | If enabled and on the classpath |
|Integration Patterns |Spring Integration | If on the classpath |
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 Boot 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:
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany</groupId>
<artifactId>myproject</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>{{project.version}}</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-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 first dependency adds Spring Boot auto
configuration and the Tomcat container to your application, and the
second one adds some more opinionated stuff like the default
management endpoints. If you prefer Jetty you can just add the
embedded Jetty jars to your classpath instead of Tomcat (once you
exclude the `spring-starter-tomcat` dependency).
## Adding a business endpoint
To do something useful to your business you need to add at least one
endpoint. An endpoint can be implemented as a Spring MVC
`@Controller`, e.g.
@Controller
@EnableAutoConfiguration
public class SampleController {
@RequestMapping("/")
@ResponseBody
public Map<String, String> helloWorld() {
return Collections.singletonMap("message", "Hello World");
}
public static void main(String[] args) throws Exception {
SpringApplication.run(SampleController.class, args);
}
}
You can use the main method to launch it from your project jar. You
can also launch that straight using the Spring Boot CLI (without
the `@EnableAutoConfiguration` and even without the import statements
that your IDE will add if you are using one), if you just add
```
@Grab("org.springframework.boot:spring-boot-starter-actuator:{{project.version}}")
```
and package and run:
$ mvn package
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar
$ curl localhost:8080/
{"message": "Hello World"}
There are also some endpoins that you didn't implement by came free
with the Actuator:
$ curl localhost:8080/health
ok
$ curl localhost:8080/metrics
{"counter.status.200.health":1.0,"gauge.response.health":10.0,"mem":120768.0,"mem.free":105012.0,"processors":4.0}
`/health` is the default location for the health endpoint - it tells
you if the application is running and healthy. `/metrics` is the default
location for the metrics endpoint - it gives you basic counts and
response timing data by default but there are plenty of ways to
customize it. You can also try `/trace` and `/dump` to get some
interesting information about how and what your app is doing.
## Running the application
You can package the app and run it as a jar (as above) and that's very
convenient for production usage. Or there are other options, many of
which are more convenient at development time. Here are a few:
1. Use the Maven exec plugin, e.g.
$ mvn exec:java
2. Run directly in your IDE, e.g. Eclipse or IDEA let you right click
on a class and run it.
3. Use a different Maven plugin.
4. Find feature in Gradle that does the same thing.
5. Use the Spring executable. <!--FIXME: document this maybe.-->
## Externalizing configuration
Spring Boot likes you to externalize your configuration so you
can work with the same application code in different environments. To
get started with this you create a file in the root of your classpath
(`src/main/resources` if using Maven) - if you like YAML, you can include
`org.yaml:snakeyaml` on your runtime class path, and call the file `application.yml`,
e.g.:
server:
port: 9000
management:
port: 9001
logging:
file: target/log.out
or if you like Java `Properties` files, you can call it
`application.properties`, e.g.:
server.port: 9000
management.port: 9001
logging.file: target/log.out
Those examples are properties that Spring Boot itself binds to
out of the box, so if you make that change and run the app again, you
will find the home page on port 9000 instead of 8080:
$ curl localhost:9000/
{"message": "Hello World"}
and the management endpoints on port 9001 instead of 8080:
$ curl localhost:9001/health
ok
To externalize business configuration you can simply add a default
value to your configuration file, e.g.
server:
port: 9000
management:
port: 9001
logging:
file: target/log.out
service:
message: Awesome Message
and then bind to it in the application code. The simplest way to do
that is to simply refer to it in an `@Value` annotation, e.g.
@Controller
@EnableAutoConfiguration
public class SampleController {
@Value("${service.message:Hello World}")
private String value = "Goodbye Everyone"
@RequestMapping("/")
@ResponseBody
public Map<String, String> helloWorld() {
return Collections.singletonMap("message", message);
}
...
}
That's a little bit confusing because we have provided a message value
in three different places - in the external configuration ("Awesome
Message"), in the `@Value` annotation after the colon ("Hello World"),
and in the filed initializer ("Goodbye Everyone"). That was only to
show you how and you only need it once, so it's your choice (it's
useful for unit testing to have the Java initializer as well as the
external value). Note that the YAML object is flattened using period
separators.
For simple Strings where you have sensible defaults `@Value` is
perfect, but if you want more and you like everything strongly typed
then you can have Spring bind the properties and validate them
automatically in a separate value object. For instance:
// ServiceProperties.java
@ConfigurationProperties(name="service")
public class ServiceProperties {
private String message;
private int value = 0;
... getters and setters
}
// SampleController.java
@Controller
@EnableAutoConfiguration
@EnableConfigurationProperties(ServiceProperties.class)
public class SampleController {
@Autowired
private ServiceProperties properties;
@RequestMapping("/")
@ResponseBody
public Map<String, String> helloWorld() {
return Collections.singletonMap("message", properties.getMessage());
}
...
}
When you ask to
`@EnableConfigurationProperties(ServiceProperties.class)` you are
saying you want a bean of type `ServiceProperties` and that you want
to bind it to the Spring Environment. The Spring Environment is a
collection of name-value pairs taken from (in order of decreasing
precedence) 1) the command line, 2) the external configuration file,
3) System properties, 4) the OS environment. Validation is done based
on JSR-303 annotations by default provided that library (and an
implementation) is on the classpath.
## Adding security
If you add Spring Security java config to your runtime classpath you
will enable HTTP basic authentication by default on all the endpoints.
In the `pom.xml` it would look like this:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
Try it out:
$ curl localhost:8080/
{"status": 403, "error": "Forbidden", "message": "Access Denied"}
$ curl user:<password>@localhost:8080/
{"message": "Hello World"}
The default auto configuration has an in-memory user database with one
entry, and the `<password>` value has to be read from the logs (at
INFO level) by default. If you want to extend or expand that, or
point to a database or directory server, you can add the `@EnableGlobalAuthentication`
annotation and configure the global `AuthenticationManagerBuilder` as shown below:
@Controller
@EnableAutoConfiguration
@EnableGlobalAuthentication
public class SampleController {
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
auth.inMemoryAuthentication()
.withUser("client").password("secret").roles("USER");
}
...
}
Try it out:
$ curl user:password@localhost:8080/
{"status": 403, "error": "Forbidden", "message": "Access Denied"}
$ curl client:secret@localhost:8080/
{"message": "Hello World"}
## Adding a database
Just add `spring-jdbc` and an embedded database to your dependencies:
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.hsqldb</groupId>
<artifactId>hsqldb</artifactId>
</dependency>
Then you will be able to inject a `DataSource` into your controller:
@Controller
@EnableAutoConfiguration
@EnableConfigurationProperties(ServiceProperties.class)
public class SampleController {
private JdbcTemplate jdbcTemplate;
@Autowired
public SampleController(DataSource dataSource) {
this.jdbcTemplate = new JdbcTemplate(dataSource);
}
@RequestMapping("/")
@ResponseBody
public Map<String, String> helloWorld() {
return jdbcTemplate.queryForMap("SELECT * FROM MESSAGES WHERE ID=?", 0);
}
...
}
The app will run (with the new security configuration):
$ curl client:secret@localhost:8080/
{"error":"Internal Server Error", "status":500, "exception":...}
but there's no data in the database yet and the `MESSAGES` table
doesn't even exist, so there's an error. One easy way to fix it is
to provide a `schema.sql` script in the root of the classpath, e.g.
create table MESSAGES (
ID BIGINT NOT NULL PRIMARY KEY,
MESSAGE VARCHAR(255)
);
INSERT INTO MESSAGES (ID, MESSAGE) VALUES (0, 'Hello Phil');
Now when you run the app you get a sensible response:
$ curl client:secret@localhost:8080/
{"ID":0, "MESSAGE":"Hello Phil"}
Obviously, this is only the start, but hopefully you have a good grasp
of the basics and are ready to try it out yourself.

156
spring-boot-actuator/docs/Features.md
Unescape Escape View File

@ -1,156 +0,0 @@
# Spring Actuator Feature Guide
Here are some (most, hopefully all) the features of Spring Actuator
with some commentary to help you start using them. We
recommend you first build a project with the Actuator (e.g. the
getting started project from the main README), and then try each
feature in turn there.
Many useful features of
[Spring Boot](../../spring-boot/README.md) are all available
in an Actuator application.
TODO: group things together and break them out into separate files.
## Customizing Management Endpoints
The `ManagementProperties` are bound to application properties, and
can be used to specify
* The port that the application listens on for the management
endpoints (defaults to 8080)
* The address that the management endpoints are available on (if the
port is different to the main server port). Use this to listen only
on an internal or ops-facing network, for instance, or to only
listen for connections from localhost (by specifying "127.0.0.1")
* The context root of the management endpoints
## Error Handling
The Actuator provides an `/error` mapping by default that handles all
errors in a sensible way. If you want more specific error pages for
some conditions, the embedded servlet containers support a uniform
Java DSL for customizing the error handling. To do this you have to
have picked a container implementation (by including either Tomcat or
Jetty on the classpath), but then the API is the same. TODO: finish
this.
## Info Endpoint
By default the Actuator adds an `/info` endpoint to the main server.
It contains the commit and timestamp information from `git.properties`
(if that file exists) and also any properties it finds in the
environment with prefix "info".
To populate `git.properties` in a
Maven build you can use the excellent
[git-commit-id-plugin](https://github.com/ktoso/maven-git-commit-id-plugin).
To populate the "info" map all you need to do is add some stuff to
`application.properties`, e.g.
info.app.name: MyService
info.app.description: My awesome service
info.app.version: 1.0.0
If you are using Maven you can automcatically populate info properties
from the project using resource filtering. In your `pom.xml` you
have (inside the `<build/>` element):
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
and then in the `application.properties` you can refer to project
properties via placeholders, e.g.
project.artifactId: myproject
project.name: Demo
project.version: X.X.X.X
project.description: Demo project for info endpoint
info.build.artifact: ${project.artifactId}
info.build.name: ${project.name}
info.build.description: ${project.description}
info.build.version: ${project.version}
(notice that in the example we used `project.*` to set some values to
be used as fallbacks if the Maven resource filtering has for some
reason not been switched on).
## Security - Basic Authentication
To secure your endpoints just add Spring Security Javaconfig to the
classpath. By default HTTP Basic authentication will be applied to
every request in the main server (and the management server if it is
running on the same port). There is a single account by default, and
you can test it like this:
$ curl user:password@localhost:8080/metrics
... stuff comes out
If the management server is running on a different port it is
unsecured by default. If you want to secure it you can add a security
auto configuration explicitly
## Security - HTTPS
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 the Actuator 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 or not it is secure (even downstream of the real SSL
termination endpoint). The standard behaviour 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 switch on the valve by adding some
entries to `application.properties`, e.g.
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 an Actuator application
you just need to set `security.require_https: true` in
`application.properties`.
## Audit Events
The Actuator has a flexible audit framework that will publish events
once Spring Security is in play (authentication success and failure
and access denied exceptions by default). This can be very useful for
reporting, and also to implement a lock-out policy based on
authentication failures.
You can also choose to use the audit services for your own business
events. To do that you can either inject the existing
`AuditEventRepository` into your own components and use that directly,
or you can simply publish `AuditApplicationEvent` via the Spring
`ApplicationContext` (using `ApplicationEventPublisherAware`).
## Metrics Customization
Metrics come out on the `/metrics` endpoint. You can add additional
metrics by injecting a `MetricsRepository` into your application
components and adding metrics whenever you need to. To customize the
`MetricsRepository` itself, just add a bean definition of that type to
the application context (only in memory is supported out of the box
for now).
## Customizing the Health Indicator
The application always tells you if it's healthy via the `/health`
endpoint. By default it just responds to a GET witha 200 status and a
plain text body containing "ok". If you want to add more detailed
information (e.g. a description of the current state of the
application), just add a bean of type `HealthIndicator` to your
application context, and it will take the place of the default one.

123
spring-boot-autoconfigure/README.md
Unescape Escape View File

@ -1,123 +0,0 @@
# Spring Boot - AutoConfigure
Spring Boot AutoConfiguration attempts to automatically configure your Spring application
based on the dependencies that it declares. For example, If `HSQLDB` is on your
classpath, and you have not manually configured any database connection beans, then we
will auto-configure an in-memory database.
##Enabling auto-configuration
Add an `@EnableAutoConfiguration` annotation to your primary `@Configuration` class to
enable auto-configuration:
```java
import org.springframework.boot.autoconfigure.*;
import org.springframework.context.annotation.*;
@Configuration
@EnableAutoConfiguration
public class MyConfiguration {
}
```
Currently auto-configuration is provided for the following types of application:
* Web (Tomcat or Jetty, Spring MVC)
* JDBC (Commons DBCP, embedded databases, jdbcTemplate)
* JPA with Hibernate
* Spring Data JPA (automatically detecting `Repository` classes)
* Spring Batch (including `JobLauncherCommandLineRunner`s and database initialization)
* Thymeleaf templating
* Reactor asynchronous JVM programming
###Understanding auto-configured beans
Under the hood, auto-configuration is implemented with standard `@Configuration` classes.
Additional `@Conditional` annotations are used to constrain when the auto-configuration
should apply. Usually auto-configuration classes use `@ConditionalOnClass` and
`@ConditionalOnMissingBean` annotations. This ensures that auto-configuration only
applies when relevant classes are found and when you have not declared your own
`@Configuration`.
You can browse the source code of `spring-boot-autoconfigure` to see the `@Configuration`
classes that we provide (see the `META-INF/spring.factories` file).
> **Note:** If you are using `org.springframework.boot.SpringApplication`, you can see
> which `@Conditions` were not applied by starting your application with the `--debug`
> option.
###Disabling specific auto-configuration
All auto-configuration that we provide attempts to back away as you start to define your
own beans. If, however, you find that specific auto-configure classes are being applied
that you don't want you can use the `exclude` attribute of `@EnableAutoConfiguration`
to disable them.
```java
import org.springframework.boot.autoconfigure.*;
import org.springframework.boot.autoconfigure.jdbc.*;
import org.springframework.context.annotation.*;
@Configuration
@EnableAutoConfiguration(exclude={EmbeddedDatabaseConfiguration.class})
public class MyConfiguration {
}
```
##Condition annotations
Spring Boot Auto-Configure includes a number of `@Conditional` annotations that are used
limit when auto-configure is applied. You can reuse these in your own code by annotating
`@Configuration` classes or individual `@Bean` methods.
###Class conditions
The `ConditionalOnClass` and `ConditionalOnMissingClass` annotations allow configuration
to be skipped based on the presence or absence of specific classes. Due to the fact that
annotation meta-data is parsed using ASM you can actually use the `value` attribute to
refer to the real class, even though that class might not actually appear in the running
application classpath. You can also use the `name` attribute if you prefer to specify
the class name using a `String` value.
###Bean conditions
The `@ConditionalOnBean` and `@ConditionalOnMissingBean` annotations allow configuration
to be skipped based on the presence or absence of specific beans. You can use the `value`
attribute to specify beans by type, or `name` to specify beans by name. The `search`
attribute allows you to limit the `ApplicationContext` hierarchy that should be considered
when searching for beans.
> **Note:** `@Conditional` annotations are processed when `@Configuration` classes are
parsed. Auto-configure `@Configuration` is always parsed last (after any user defined
beans), however, if you are using these annotations on regular `@Configuration` classes,
care must be take not to refer to bean definitions that have not yet been created.
###Resource conditions
The `@ConditionalOnResource` annotation allows configuration to be skipped when a specific
resource is not present. Resources can be specified using the usual Spring conventions,
for example, `file:C:/test.dat`.
###Web Application Conditions
The `@ConditionalOnWebApplication` and `@ConditionalOnNotWebApplication` annotations
allow configuration to be skipped depending on whether the application is a
'web application'. A web application is any application that is using a Spring
`WebApplicationContext`, defines a `session` scope or has a `StandardServletEnvironment`.
###SpEL expression conditions
The `@ConditionalOnExpression` annotation allows configuration to be skipped based on the
result of a SpEL expression.
##Writing additional auto-configuration
You can easily add auto-configuration to your own libraries, simply create a regular
`@Configuration` class and annotate it with appropriate `@Conditional` restrictions.
Spring Boot checks for presence of a `META-INF/spring.factories` file within your
published jar. The file should list your configuration classes under the
`org.springframework.boot.autoconfigure.EnableAutoConfiguration` key.
```
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.mycorp.libx.autoconfigure.LibXAutoConfiguration,\
com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration
```
You can use the `@AutoConfigureAfter` or `@AutoConfigureBefore` annotations if your
configuration needs to be applied in a specific order. For example, if you provide
web specific configuration you may need to be applied after `WebMvcAutoConfiguration`.
#Further reading
For more information about any of the classes or interfaces discussed in the document
please refer to the extensive project Javadoc. If you are just starting out with Spring
Boot take a look at the [getting started](../README.md) guide.

215
spring-boot-cli/README.md
Unescape Escape View File

@ -1,215 +0,0 @@
# Spring Boot - CLI
## Installing the CLI
You need [Java SDK v1.6](http://www.java.com) or higher to run the command line tool
(there are even some issues with the `1.7.0_25` build of openjdk, so stick to earlier
builds or use `1.6` for preference). You should check your current Java installation
before you begin:
$ java -version
### Manual installation
You can download the Spring CLI distribution from the Spring software repository:
* [spring-boot-cli-1.0.0.RC4-bin.zip](http://repo.spring.io/milestone/org/springframework/boot/spring-boot-cli/1.0.0.RC4/spring-boot-cli-1.0.0.RC4-bin.zip)
* [spring-boot-cli-1.0.0.RC4-bin.tar.gz](http://repo.spring.io/milestone/org/springframework/boot/spring-boot-cli/1.0.0.RC4/spring-boot-cli-1.0.0.RC4-bin.tar.gz)
Cutting edge [snapshot distributions](http://repo.spring.io/snapshot/org/springframework/boot/spring-boot-cli/)
are also available.
Once downloaded, follow the
[INSTALL](https://github.com/spring-projects/spring-boot/blob/master/spring-boot-cli/src/main/content/INSTALL.txt) instructions
from the unpacked archive. In summary: there is a `spring` script
(`spring.bat` for Windows) in a `bin/` directory in the `.zip` file,
or alternatively you can use `java -jar` with the `.jar` file (the
script helps you to be sure that the classpath is set correctly).
### Installation with GVM
GVM (the Groovy Environment Manager) can be used for managing multiple
versions of verious Groovy and Java binary packages, including Groovy
itself and the Spring Boot CLI. Get `gvm` from
[the gvm home page](http://gvmtool.net) and install Spring Boot with
$ gvm install springboot
$ spring --version
Spring Boot v1.0.0.RC4
> **Note:** If you are developing features for the CLI and want easy access to the version you just built, follow these extra instructions.
$ gvm install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-1.0.0.BUILD-SNAPSHOT-bin/spring-1.0.0.BUILD-SNAPSHOT/
$ gvm use springboot dev
$ spring --version
Spring CLI v1.0.0.BUILD-SNAPSHOT
This will install a local instance of `spring` called the `dev` instance inside your gvm repository. It points at your target build location, so every time you rebuild Spring Boot, `spring` will be up-to-date.
You can see it by doing this:
$ gvm ls springboot
```
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 1.0.0.RC4
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
```
### OSX Homebrew installation
If you are on a Mac and using [homebrew](http://brew.sh/), all you need to do to install
the Spring Boot CLI is:
```
$ brew install http://repo.spring.io/install/spring-boot-cli.rb
```
Homebrew will install `spring` to `/usr/local/bin`. Now you can jump right to a
[quick start example](#quick-start-script-example).
> **Note:** If you don't see the formula, you're installation of brew might be
> out-of-date. Just execute `brew update` and try again.
### Quick start script example
Here's a really simple web application. Create a file called `app.groovy`:
```groovy
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
return "Hello World!"
}
}
```
Then run it from a shell:
```
$ spring run app.groovy
```
> **Note:** It will take some time when you first run the application as dependencies
> are downloaded, subsequent runs will be much quicker.
Open [http://localhost:8080](http://localhost:8080) in your favorite web browser and you
should see the following output:
> Hello World!
## Testing Your Code
The Spring Boot CLI has a `test` command. Example usage:
```
$ spring test app.groovy tests.groovy
Total: 1, Success: 1, : Failures: 0
Passed? true
```
Where `tests.groovy` contains JUnit `@Test` methods or Spock
`Specification` classes. All the common framework annotations and
static methods should be available to you without having to import
them. Example with JUnit (for the above application):
```groovy
class ApplicationTests {
@Test
void homeSaysHello() {
assertEquals("Hello World", new ThisWillActuallyRun().home())
}
}
```
You can add more tests by adding additional
files, or you might prefer to put them in a special directory.
## Applications with Multiple Source Files
You can use shell globbing to pick up multiple files in a single
directory, e.g.
```
$ spring run *.groovy
```
and this enables you to easily segregate your test or spec code from
the main application code, if that's what you prefer, e.g.
```
$ spring test app/*.groovy test/*.groovy
```
## Beans DSL
Spring has native support for a `beans{}` DSL (borrowed from
[Grails](http://grails.org)), and you can embedd bean definitions in
your Groovy application scripts using the same format. This is
sometimes a good way to include external features like middleware
declarations. E.g.
```groovy
@Configuration
class Application implements CommandLineRunner {
@Autowired
SharedService service
@Override
void run(String... args) {
println service.message
}
}
import my.company.SharedService
beans {
service(SharedService) {
message "Hello World"
}
}
```
You can mix class declarations with `beans{}` in the same file as long
as they stay at the top level, or you can put the beans DSL in a
separate file if you prefer.
## Commandline Completion
Spring Boot CLI ships with a script that provides command completion
in a standard bash-like shell. You can source the script (also named
`spring`) in any shell, or put it in your personal or system-wide bash
completion initialization. On a Debian system the system-wide scripts
are in `/etc/bash_completion.d` and all scripts in that directory are
executed in a new shell. To run the script manually, e.g. if you have
installed using GVM
```
$ . ~/.gvm/springboot/current/bash_completion.d/spring
$ spring <HIT TAB HERE>
clean -d debug help run test version
```
## Packaging Your Application
You can use the `jar` command to package your application into a
self-contained executable jar file. For example:
```
$ spring jar my-app.jar *.groovy
```
The resulting jar will containe the classes produced by compiling
the application and all of the application's dependencies such that
it can then be run using `java -jar`. The jar file will also contain
entries from the application's classpath. See the output of
`spring help jar` for more information.

4
spring-boot-samples/README.md
Unescape Escape View File

@ -1,4 +0,0 @@
# Spring Boot - Samples
> We are currently still working on documentation for Spring Boot. Please check back
> in the future.

23
spring-boot-samples/spring-boot-sample-actuator-log4j/README.md
Unescape Escape View File

@ -1,23 +0,0 @@
# Spring Boot Actuator Sample
You can build this sample using Maven (>3) or Gradle (1.6).
With Maven:
```
$ mvn package
$ java -jar target/*.jar
```
Then access the app via a browser (or curl) on http://localhost:8080 (the user name is
"user" and look at the INFO log output for the password to login).
With gradle:
```
$ gradle build
$ java -jar build/libs/*.jar
```
The gradle build contains an intentionally odd configuration to exclude the security
dependencies from the executable JAR. So the app run like this behaves differently than
the one run from the Maven-built JAR file. See comments in the `build.gradle` for details.

21
spring-boot-samples/spring-boot-sample-actuator/README.md
Unescape Escape View File

@ -1,21 +0,0 @@
# Spring Boot Actuator Sample
You can build this sample using Maven (>3) or Gradle (1.6).
With Maven:
```
$ mvn package
$ java -jar target/*.jar
```
Then access the app via a browser (or curl) on http://localhost:8080 (the user name is "user" and look at the INFO log output for the password to login).
With gradle:
```
$ gradle build
$ java -jar build/libs/*.jar
```
The gradle build contains an intentionally odd configuration to exclude the security dependencies from the executable JAR. So the app run like this behaves differently than the one run from the Maven-built JAR file. See comments in the `build.gradle` for details.

19
spring-boot-samples/spring-boot-sample-simple/README.md
Unescape Escape View File

@ -1,19 +0,0 @@
# Spring Boot Simple Sample
You can build this sample using Maven (>3) or Gradle (1.6).
With Maven:
```
$ mvn package
$ java -jar target/*.jar
```
The app prints a Hello message on the console.
With gradle:
```
$ gradle build
$ java -jar build/libs/*.jar
```

211
spring-boot-starters/README.md
Unescape Escape View File

@ -1,211 +0,0 @@
# Spring Boot - Starters
Starters are a set of convenient dependency descriptors that you can
include in your application. You get a one-stop-shop for all the
Spring and related technology that you need without having to hunt
through sample code and copy paste loads of dependency
descriptors. For example, if you want to get started using Spring and
JPA for database access just include the
`spring-boot-starter-data-jpa` dependency in your project, and you are
good to go. The starters contain a lot of the dependencies that you
need to get a project up and running quickly and with a consistent,
supported set of managed transitive dependencies.
## Building a Spring Boot Project with Maven
The quickest way to get started with a new project is to use the
spring-boot-starter-parent, e.g.
```xml
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.0.0.RC4</version>
</parent>
```
The parent pom adds two main fetaures to your project:
* dependency management configuration, so you don't have to specify
versions or excludes with your own dependencies, as long as they are
part of the Spring Boot stack
* plugin configuration, so you don't have to configure some common
settings in the main Maven plugins used to get a project off the
ground (e.g. the
[Spring Boot Maven plugin](../spring-boot-tools/spring-boot-maven-plugin/README.md))
As an example, if you want to build a simple RESTful web service with
embedded Tomcat, you only need one dependency:
```xml
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
```
And if you want to use the Spring Boot plugin to package the project
as an executable JAR (or run it from source code), you only need to
add the plugin (not configure it, unless you want to change the
settings in the parent):
```xml
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
```
If you need to access milestone or snapshot builds from Spring
projects, you can optionallyt add repositories, as follows:
```xml
<repositories>
<repository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
<repository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</pluginRepository>
</pluginRepositories>
```
The repositories cannot all be defined in the parent (at least one
will be required to resolve the parent itself).
### Using Your Own Parent POM
If you don't want to use the Spring Boot starter parent, you can use
your own and still keep the benefit of the dependency management (but
not the plugin management) using
["scope=import"](http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html). Example:
```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.0.0.RC4</version>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
```
(It actually doesn't matter if you use "spring-boot-starter-parent" or
"spring-boot-dependencies".)
### Samples
All the
[Spring Boot Samples](../spring-boot-samples)
come with a `pom.xml`, but they use a different parent to
spring-boot-starter-parent (although that pom is one of their
ancestors). Other useful places to get clean projects with a
`pom.xml` that works as quickly as possible:
* The
[Getting Started Guides on spring.io](http://spring.io/guides/gs) are
all available in [github](https://github.com/spring-guides), or you
can copy paste from the guides themselves (all the code is on the web
page).
* The same guides are available as working projects in
[Spring Tool Suite](http://spring.io/tools/sts)(STS) (an Eclipse
plugin feature set), and so is a starter project template generator
(via `File->New->Spring Starter Project`).
* The Spring Starter Project feature in STS is backed by a web
application at [start.spring.io](http://start.spring.io), which you
can also use yourself to download ZIP files of the starter projects.
## Building With Gradle
If you prefer to build your project with Gradle then similar features
are available to you as to Maven users. The starter projects work in
exactly the same way, for instance, so a typical project might have a
`build.gradle` like this:
```groovy
buildscript {
ext {
springBootVersion = '1.0.0.RC4'
}
repositories {
mavenCentral()
maven { url "http://repo.spring.io/libs-milestone" }
}
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
}
}
apply plugin: 'java'
apply plugin: 'spring-boot'
jar {
baseName = 'spring-boot-sample-simple'
version = '0.5.0'
}
repositories {
mavenCentral()
maven { url "http://repo.spring.io/libs-milestone" }
}
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
}
task wrapper(type: Wrapper) { gradleVersion = '1.6' }
```
This build is for a simple RESTful web service (with embedded
Tomcat). Notice that the dependencies do not have explicit version
numbers. This works for Spring Boot dependencies, but also anything
else that is explicitly managed by the Spring Boot Starter parent.
Versionless dependency resolution is a feature of the
[Spring Boot Gradle Plugin](../spring-boot-tools/spring-boot-gradle-plugin/README.md),
which also gives you a "run from source" feature ("gradle bootRun")
and an enhanced JAR/WAR packaging feature for executable archives
("gradle build").
### Samples
Most of the samples mentioned above for Maven users are also buildable
using Gradle. Only some of the
[Spring Boot Samples](../spring-boot-samples)
come with a `build.gradle`. The Spring Starter Project feature in STS
produces a Maven project. But web application at
[start.spring.io](http://start.spring.io) can generate Gradle build
files for the same projects (just download it with a browser or
command line).

10
spring-boot-tools/README.md
Unescape Escape View File

@ -1,10 +0,0 @@
# Spring Boot - Tools
Spring Boot Tools provides a logical grouping for our various build system plugins, and
the modules that support them. We provide a
[spring-boot-maven-plugin](spring-boot-maven-plugin) and
[spring-boot-gradle-plugin](spring-boot-gradle-plugin) for Maven and Gradle respectively.
If you are interested in how we support executable archives, take a look at the
[spring-boot-loader](spring-boot-loader) module. If you need to create executable
archives from a different build system,
[spring-boot-loader-tools](spring-boot-loader-tools) may help.

4
spring-boot-tools/spring-boot-dependency-tools/README.md
Unescape Escape View File

@ -1,4 +0,0 @@
# Spring Boot - Dependency Tools
The Spring Boot Dependency Tools module provides support utilities to help when resolving
'blessed' Spring Boot dependencies. It basically provides programmatic access to the
managed dependencies section of `spring-boot-dependencies/pom.xml`

192
spring-boot-tools/spring-boot-gradle-plugin/README.md
Unescape Escape View File

@ -1,192 +0,0 @@
# Spring Boot - Gradle Plugin
The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, allowing you to
package executable jar or war archives, run Spring Boot applications and remove version
information from your `build.gradle` file.
## Including the plugin
To use the Spring Boot Gradle Plugin simply include a `buildscript` dependency and apply
the `spring-boot` plugin:
```groovy
buildscript {
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:{{project.version}}")
}
}
apply plugin: 'spring-boot'
```
If you are using a milestone or snapshot release you will also need to add appropriate
`repositories` reference:
```groovy
buildscript {
repositories {
maven.url "http://repo.spring.io/snapshot"
maven.url "http://repo.spring.io/milestone"
}
// ...
}
```
## Declaring dependencies without versions
The `spring-boot` plugin will register a custom Gradle `ResolutionStrategy` with your
build that allows you to omit version numbers when declaring dependencies to known
artifacts. All artifacts with a `org.springframework.boot` group ID, and any of the
artifacts declared in the `managementDependencies` section of the `spring-dependencies`
POM can have their version number resolved automatically.
Simply declare dependencies in the usual way, but leave the version number empty:
```groovy
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
compile("org.thymeleaf:thymeleaf-spring4")
compile("nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect")
}
```
## Packaging executable jar and war files
Once the `spring-boot` plugin has been applied to your project it will automatically
attempt to rewrite archives to make them executable using the `bootRepackage` task. You
should configure your project to build a jar or war (as appropriate) in the usual way.
The main class that you want to launch can either be specified using a configuration
option, or by adding a `Main-Class` attribute to the manifest. If you don't specify a
main class the plugin will search for a class with a
`public static void main(String[] args)` method.
To build and run a project artifact, you do something like this:
```
$ gradle build
$ java -jar build/libs/mymodule-0.0.1-SNAPSHOT.jar
```
### Running a Project in Place
To run a project in place without building a jar first you can use the "bootRun" task:
```
$ gradle bootRun
```
Running this way makes your static classpath resources (i.e. in
`src/main/resources` by default) reloadable in the live application,
which can be helpful at development time.
### Repackage configuration
The gradle plugin automatically extends your build script DSL with a `springBoot` element
for configuration. Simply set the appropriate properties as you would any other gradle
extension:
```groovy
springBoot {
backupSource = false
}
```
### Repackage with Custom Gradle Configuration
Sometimes it may be more appropriate to not package default dependencies resolved from
`compile`, `runtime` and `provided` scopes. If created executable jar file
is intended to be run as it is you need to have all dependencies in it, however
if a plan is to explode a jar file and run main class manually you may already
have some of the libraries available via `CLASSPATH`. This is a situation where
you can repackage boot jar with a different set of dependencies. Using a custom
configuration will automatically disable dependency resolving from
`compile`, `runtime` and `provided` scopes. Custom configuration can be either
defined globally inside `springBoot` or per task.
```groovy
task clientJar(type: Jar) {
appendix = 'client'
from sourceSets.main.output
exclude('**/*Something*')
}
task clientBoot(type: BootRepackage, dependsOn: clientJar) {
withJarTask = clientJar
customConfiguration = "mycustomconfiguration"
}
```
In above example we created a new `clientJar` Jar task to package a customized
file set from your compiled sources. Then we created a new `clientBoot`
BootRepackage task and instructed it to work with only `clientJar` task and
`mycustomconfiguration`.
```groovy
configurations {
mycustomconfiguration.exclude group: 'log4j'
}
dependencies {
mycustomconfiguration configurations.runtime
}
```
Configuration we are referring to in `BootRepackage` is a normal
Gradle configuration. In above example we created a new configuration
named `mycustomconfiguration` instructing it to derive from a `runtime`
and exclude `log4j` group. If `clientBoot` task is executed, repackaged
boot jar will have all dependencies from a runtime but no
log4j jars.
The following configuration options are available:
| Name | Type | Description | Default Value |
|-----------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
| mainClass | String | The main class that should be run. If not specified the value from the manifest will be used, or if no manifest entry is the archive will be searched for a suitable class | |
| providedConfiguration | String | The name of the provided configuration | providedRuntime |
| backupSource | boolean | If the original source archive should be backed-up before being repackaged | true |
| customConfiguration | String | The name of the custom configuration | none |
| layout | String | The type of archive (which corresponds to how the dependencies are layed out inside it). Defaults to a guess based on the archive type. |
## Further Reading
For more information on how Spring Boot Loader archives work, take a look at the
[spring-boot-loader](../spring-boot-loader/README.md) module. If you prefer using Maven to
build your projects we have a [spring-boot-maven-plugin](../spring-boot-maven-plugin/README.md).
### Understanding how Boot Gradle Plugin Works
When `spring-boot` is applied to your Gradle project a default task
named `bootRepackage` is created automatically. Boot repackage task
depends on Gradle `assemble` task and when executed, it tries to find
all jar artifacts whose qualifier is empty(meaning i.e. tests and
sources jars are automatically skipped).
Because on default every repackage task execution will find all
created jar artifacts, the order of Gradle task execution is
important. This is not going to be an issue if you have a normal
project setup where only one jar file is created. However if you are
planning to create more complex project setup with custom Jar and
BootRepackage tasks, there are few tweaks to consider.
```groovy
jar.enabled = false
bootRepackage.enabled = false
```
Above example simply disables default `jar` and `bootRepackage` tasks.
This would be all right if you are just creating custom jar files
out from your project. You could also just disable default
`bootRepackage` task.
```groovy
bootRepackage.withJarTask = jar
```
Above example simply instructs default `bootRepackage` task to only
work with a default `jar` task.
```groovy
task bootJars
bootJars.dependsOn = [clientBoot1,clientBoot2,clientBoot3]
build.dependsOn(bootJars)
```
If you still have a default project setup where main jar file is
created and repackaged to be used with boot and you still want to
create additional custom jar files out from your project, you
could simple combine you custom repackage tasks together and
create dependency to your build so that `bootJars` task would
be run after the default `bootRepackage` task is executed.
All the above tweaks are usually used to avoid situation where
already created boot jar is repackaged again. Repackaging
an existing boot jar will not break anything but you may
get unnecessary dependencies in it.

52
spring-boot-tools/spring-boot-loader-tools/README.md
Unescape Escape View File

@ -1,52 +0,0 @@
# Spring Boot - Loader Tools
The Spring Boot Loader Tools module provides support utilities to help when creating
[Spring Boot Loader](../spring-boot-loader/README.md) compatible archives. This module is
used by the various build system plugins that we provide.
> **Note:** The quickest way to build a compatible archive is to use the
> [spring-boot-maven-plugin](../spring-boot-maven-plugin/README.md) or
> [spring-boot-gradle-plugin](../spring-boot-gradle-plugin/README.md).
## Repackaging archives
To repackage an existing archive so that it becomes a self-contained executable archive
use `org.springframework.boot.loader.tools.Repackager`. The `Repackager` class takes a
single constructor argument that refers to an existing jar or war archive. Use one of the
two available `repackage()` methods to either replace the original file or write to a new
destination. Various settings can also be configured on the repackager before it is
run.
## Libraries
When repackaging an archive you can include references to dependency files using the
`org.springframework.boot.loader.tools.Libraries` interface. We don't provide any
concrete implementations of `Libraries` here as they are usually build system specific.
If your archive already includes libraries you can use `Libraries.NONE`
## Finding a main class
If you don't use `Repackager.setMainClass()` to specify a main class, the repackager will
use [ASM](http://asm.ow2.org/) to read class files and attempt to find a suitable class.
The first class with a `public static void main(String[] args)` method will be used.
Searching is performed using a breadth first algorithm, with the assumption that the main
class will appear high in the package structure.
## Example
Here is a typical example repackage:
```java
Repackager repackager = new Repackager(sourceJarFile);
repackager.setBackupSource(false);
repackager.repackage(new Libraries() {
@Override
public void doWithLibraries(LibraryCallback callback) throws IOException {
// Build system specific implementation, callback for each dependency
// callback.library(nestedFile, LibraryScope.COMPILE);
}
});
```
## Further Reading
For more information on how Spring Boot Loader archives work take a look at the
[spring-boot-loader](../spring-boot-loader/README.md) module. If you want to see how we use this
library the [Maven](../spring-boot-maven-plugin/README.md) and
[Gradle](../spring-boot-gradle-plugin/README.md) plugins are good place to start.

228
spring-boot-tools/spring-boot-loader/README.md
Unescape Escape View File

@ -1,228 +0,0 @@
# Spring Boot - Loader
The Spring Boot Loader module allows JAR and WAR files that contain
nested dependencies to be run using `java -jar archive.jar`. There are
3 launcher classes (`JarLauncher`, `WarLauncher` and
`PropertiesLauncher`). Their purpose is to load resources (.class
files etc.) from nested JAR files or JAR files in directories (as
opposed to explicitly on the classpath). In the case of the
`[Jar|War]Launcher` the nested paths are fixed `(lib/*.jar` and
`lib-provided/*.jar` for the WAR case) so you just add extra JARs in
those locations if you want more. The `PropertiesLauncher` looks in
`lib/` by default, but you can add additional locations by setting an
environment variable `LOADER_PATH`or `loader.path` in
`application.properties` (colon-separated list of directories or archives).
> **Note:** The quickest way to build a compatible archive is to use the
> [spring-boot-maven-plugin](../spring-boot-maven-plugin/README.md) or
> [spring-boot-gradle-plugin](../spring-boot-gradle-plugin/README.md).
## Nested JARs
Java does not provide any standard way to load nested jar files (i.e. jar files that
are themselves contained within a jar). This can be problematic if you are looking
to distribute a self contained application that you can just run from the command line
without unpacking.
To solve this problem, many developers use 'shaded' jars. A shaded jar simply packages
all classes, from all jars, into a single 'uber jar'. The problem with shaded jars is
that it becomes hard to see which libraries you are actually using in your application.
It can also be problematic if the the same filename is used (but with different content)
in multiple jars. Spring Boot takes a different approach and allows you to actually nest
jars directly.
### JAR file structure
Spring Boot Loader compatible jar files should be structured in the following way:
```
example.jar
|
+-META-INF
| +-MANIFEST.MF
+-org
| +-springframework
| +-boot
| +-loader
| +-<spring boot loader classes>
+-com
| +-mycompany
| + project
| +-YouClasses.class
+-lib
+-dependency1.jar
+-dependency2.jar
```
Dependencies should be placed in a nested `lib` directory.
See [executable-jar](src/it/executable-jar) for an example project.
### WAR file structure
Spring Boot Loader compatible war files should be structured in the following way:
```
example.jar
|
+-META-INF
| +-MANIFEST.MF
+-org
| +-springframework
| +-boot
| +-loader
| +-<spring boot loader classes>
+-WEB-INF
+-classes
| +-com
| +-mycompany
| +-project
| +-YouClasses.class
+-lib
| +-dependency1.jar
| +-dependency2.jar
+-lib-provided
+-servlet-api.jar
+-dependency3.jar
```
Dependencies should be placed in a nested `WEB-INF/lib` directory. Any dependencies
that are required when running embedded but are not required when deploying to
a traditional web container should be placed in `WEB-INF/lib-provided`.
See [executable-war](src/it/executable-war) for an example project.
## RandomAccessJarFile
The core class used to support loading nested jars is
`org.springframework.boot.loader.jar.RandomAccessJarFile`. It allows you load jar
content from a standard jar file or from nested child jar data. When first loaded, the
location of each `JarEntry` is mapped to a physical file offset of the outer jar:
```
myapp.jar
+---------+---------------------+
| | /lib/mylib.jar |
| A.class |+---------+---------+|
| || B.class | B.class ||
| |+---------+---------+|
+---------+---------------------+
^ ^ ^
0063 3452 3980
```
The example above shows how `A.class` can be found in `myapp.jar` position `0063`.
`B.class` from the nested jar can actually be found in `myapp.jar` position `3452`
and `B.class` is at position `3980`.
Armed with this information, we can load specific nested entries by simply seeking to
appropriate part if the outer jar. We don't need to unpack the archive and we don't
need to read all entry data into memory.
### Compatibility
Spring Boot Loader strives to remain compatible with existing code and libraries. The
`RandomAccessJarFile` extends from `java.util.jar.JarFile` and should work as a drop-in
replacement. The `RandomAccessJarFile.getURL()` method will return a `URL` that opens
a `java.net.JarURLConnection` compatible connection. `RandomAccessJarFile` URLs can
be used with Java's `URLClassLoader`.
## Launching
The `org.springframework.boot.loader.Launcher` class can be used to run your packaged
application. It takes care of setting up an appropriate `URLClassLoader` and calling
your `main()` method.
### Launcher manifest
You need specify an appropriate `Launcher` as the `Main-Class` attribute of
`META-INF/MANIFEST.MF`. The actual class that you want to launch (i.e. the class that
you wrote that contains a `main` method) should be specified in the `Start-Class`
attribute.
For example, here is a typical `MANIFEST.MF` for a executable jar file:
```
Main-Class: org.springframework.boot.loader.JarLauncher
Start-Class: com.mycompany.project.MyApplication
```
For a war file, it would be:
```
Main-Class: org.springframework.boot.loader.WarLauncher
Start-Class: com.mycompany.project.MyApplication
```
> **Note:** You do not need to specify `Class-Path` entries in your manifest file, the
> classpath will be deduced from the nested jars.
### Exploded archives
Certain PaaS implementations may choose to unpack archives before they run. For example,
Cloud Foundry operates in this way. You can run an unpacked archive by simply starting
the appropriate launcher:
```
$ unzip -q myapp.jar
$ java org.springframework.boot.loader.JarLauncher
```
## PropertiesLauncher Features
`PropertiesLauncher` has a few special features that can be enabled
with external properties (System properties, environment variables,
manifest entries or `application.properties`).
| Key | Purpose | Typical value |
|------------|---------|---------------|
|loader.path |Classpath (colon-separated) |lib:${HOME}/app/lib|
|loader.home |Location of additional properties file (defaults to `${user.dir}`) |file:///opt/app|
|loader.args |Default arguments for the main method (space separated) ||
|loader.main |Name of main class to launch | com.app.Application |
|loader.config.name|Name of properties file (default "application") | loader|
|loader.config.location|Path to properties file (default "application/.properties") | classpath:loader.properties|
|loader.system|Boolean flag to indicate that all properties should be added to System properties (default false)|true|
Manifest entry keys are formed by capitalizing intial letters of words
and changing the separator to '-' from '.' (e.g. "Loader-Path"). The
exception is "loader.main" which is looked up as "Start-Class" in the
manifest for compatibility with `JarLauncher`).
Environment variables can be capitalized with underscore separators
instead of periods.
* `loader.home` is the directory location of an additional properties
file (overriding the default) as long as `loader.config.location` is
not specified
* `loader.path` can contain directories (scanned recursively for jar
and zip files), archive paths, or wildcard patterns (for the default
JVM behaviour)
* Placeholder replacement is done from System and environment
variables plus the properties file itself on all values before use.
## Restrictions
There are a number of restrictions that you need to consider when working with a Spring
Boot Loader packaged application.
### Zip entry compression
The `ZipEntry` for a nested jar must be saved using the `ZipEntry.STORED` method. This
is required so that we can seek directly to individual content within the nested jar.
The content of the nested jar file itself can still be compressed, as can any other
entries in the outer jar. You can use the Spring Boot
[Maven](../spring-boot-maven-plugin/README.md) or
[Gradle](../spring-boot-gradle-plugin/README.md) plugins
to ensure that your archives are written correctly.
### System ClassLoader
Launched applications should use `Thread.getContextClassLoader()` when loading classes
(most libraries and frameworks will do this by default). Trying to load nested jar
classes via `ClassLoader.getSystemClassLoader()` will fail. Please be aware that
`java.util.Logging` always uses the system classloader, for this reason you should
consider a different logging implementation.
### Alternatives
If the above restrictions mean that you cannot use Spring Boot Loader the following
alternatives could be considered:
* [Maven Shade Plugin](http://maven.apache.org/plugins/maven-shade-plugin/)
* [JarClassLoader](http://www.jdotsoft.com/JarClassLoader.php)
* [OneJar](http://one-jar.sourceforge.net)
## Further Reading
For more information about any of the classes or interfaces discussed in the document
please refer to the project Javadoc. If you need to build a compatible archives see the
[spring-boot-maven-plugin](../spring-boot-maven-plugin/README.md) or
[spring-boot-gradle-plugin](../spring-boot-gradle-plugin/README.md). If you are not using
Maven or Gradle [spring-boot-loader-tools](../spring-boot-loader-tools/README.md) provides
some useful utilities to rewite existing zip files.

185
spring-boot-tools/spring-boot-maven-plugin/README.md
Unescape Escape View File

@ -1,185 +0,0 @@
# Spring Boot - Maven Plugin
The Spring Boot Maven Plugin provides Spring Boot support in Maven,
allowing you to package executable jar or war archives and run an
application in-place. To use it you must be using Maven 3 (or better).
## Including the plugin
To use the Spring Boot Maven Plugin simply include the appropriate XML in the `plugins`
section of your `pom.xml`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<!-- ... -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>{{project.version}}</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
```
This configuration will repackage a JAR or WAR that is built in the
"package" phase of the Maven lifecycle, so
```
$ mvn package
$ ls target/*.jar
target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original
```
will reveal the result. If you don't include the `<execution/>`
configuration as above you can run the plugin on its own, but only if
the package goal is used as well, e.g.
```
$ mvn package spring-boot:repackage
```
will have the same effect as above.
If you are using a milestone or snapshot release you will also need to add appropriate
`pluginRepository` elements:
```xml
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</pluginRepository>
</pluginRepositories>
```
## Packaging executable jar and war files
Once `spring-boot-maven-plugin` has been included in your `pom.xml` it will
automatically attempt to rewrite archives to make them executable using the
`spring-boot:repackage` goal. You should configure your project to build a jar or war
(as appropriate) using the usual `packaging` element:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<!-- ... -->
<packaging>jar</packaging>
<!-- ... -->
</project>
```
Your existing archive will be enhanced by Spring Boot during the `package`
phase. The main class that you want to launch can either be specified using a
configuration option, or by adding a `Main-Class` attribute to the manifest in the usual
way. If you don't specify a main class the plugin will search for a class with a
`public static void main(String[] args)` method.
To build and run a project artifact, you do something like this:
```
$ mvn package
$ java -jar target/mymodule-0.0.1-SNAPSHOT.jar
```
### Repackage configuration
The following configuration options are available for the `spring-boot:repackage` goal:
**Required Parameters**
| Name | Type | Description | Default Value |
|-----------------|--------|--------------------------------------------|----------------------------|
| outputDirectory | File | Directory containing the generated archive | ${project.build.directory} |
| finalName | String | Name of the generated archive | ${project.build.finalName} |
**Optional Parameters**
| Name | Type | Description |
|-----------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| classifier | String | Classifier to add to the artifact generated. If given, the artifact will be attached. If this is not given, it will merely be written to the output directory according to the finalName |
| mainClass | String | The name of the main class. If not specified the first compiled class found that contains a 'main' method will be used |
| layout | String | The type of archive (which corresponds to how the dependencies are layed out inside it). Defaults to a guess based on the archive type. |
The plugin rewrites your manifest, and in particular it manages the
`Main-Class` and `Start-Class` entries, so if the defaults don't work
you have to configure those there (not in the jar plugin). The
`Main-Class` in the manifest is actually controlled by the `layout`
property of the boot plugin, e.g.
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>{{project.version}}</version>
<configuration>
<mainClass>${start-class}</mainClass>
<layout>ZIP</layout>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
The layout property defaults to a guess based on the archive type (JAR
or WAR). For the `PropertiesLauncher` the layout is "ZIP" (even though
the output might be a JAR file).
## Running applications
The Spring Boot Maven Plugin includes a `run` goal which can be used to launch your
application from the command line. Type the following from the root of your maven
project:
```
$ mvn spring-boot:run
```
By default, any `src/main/resources` folder will be added to the application classpath
when you run via the maven plugin. This allows hot refreshing of resources which can be
very useful when web applications. For example, you can work on HTML, CSS or JavaScipt
files and see your changes immediately without recompiling your application. It is also
a helpful way of allowing your front end developers to work without needing to download
and install a Java IDE.
### Run configuration
The following configuration options are available for the `spring-boot:run` goal:
**Required Parameters**
| Name | Type | Description | Default Value |
|--------------------------------------|---------|----------------------------------------------------------------------------------------------|----------------------------------|
| classesDirectrory | File | Directory containing the classes and resource files that should be packaged into the archive | ${project.build.outputDirectory} |
**Optional Parameters**
| Name | Type | Description | Default Value |
|--------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|
| arguments (or -Drun.arguments) | String[] | Arguments that should be passed to the application | |
| addResources (or -Drun.addResources) | boolean | Add maven resources to the classpath directly, this allows live in-place editing or resources. Since resources will be added directly, and via the target/classes folder they will appear twice if ClassLoader.getResources() is called. In practice however most applications call ClassLoader.getResource() which will always return the first resource | true |
| mainClass | String | The name of the main class. If not specified the first compiled class found that contains a 'main' method will be used | |
| folders | String[] | Folders that should be added to the classpath | ${project.build.outputDirectory} |
## Further Reading
For more information on how Spring Boot Loader archives work, take a look at the
[spring-boot-loader](../spring-boot-loader/README.md) module. If you prefer using Gradle to
build your projects we have a [spring-boot-gradle-plugin](../spring-boot-gradle-plugin/README.md).

516
spring-boot/README.md
Unescape Escape View File

@ -1,516 +0,0 @@
# 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 wish 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 '.yml' 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`.
#### Adding active profiles
The `spring.profiles.active` property follows the same ordering rules as other
properties, the highest `PropertySource` will win. This means that you can specify
active profiles in `application.properties` then **replace** them using the command line
switch.
Sometimes it is useful to have profile specific properties that **add** to the active
profiles rather than replace them. The `+` prefix can be used to add active profiles.
For example, when an application with following properties is run using the switch
`--spring.profiles.active=prod` the `proddb` and `prodmq` profiles will also be activated:
```yaml
---
my.property: fromyamlfile
---
spring.profiles: prod
spring.profiles.active: +proddb,+prodmq
```
### 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.
### JSP limitations
When running a Spring Boot application that uses
an embedded servlet container (and is packaged as an executable
archive), there are some limitations in the JSP support.
* With Tomcat it should work if you use WAR packaging, i.e. an
executable WAR will work, and will also be deployable to a standard
container (not limited to, but including Tomcat). An executable JAR
will not work because of a hard coded file pattern in Tomcat.
* Jetty does not currently work as an embedded container with
JSPs. There should be a way to make it work, so hopefully someone
can figure it out (pull requests always welcome).
There is a
[JSP sample](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-samples/spring-boot-sample-web-jsp)
so you can see how to set things up.
## 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:
```
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
```
### YAML shortcomings
YAML files can't (currently) be loaded via the `@PropertySource` annotation. So in the case
that you need to load values that way, you need to use a properties file.
## 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).
Write Preview
Loading…
Cancel
Save