Documentation
Phillip Webb
11 years ago
parent
ec36efd50f
commit
9cf59050d3
@ -1,188 +1,190 @@
|
||||
# Spring Boot
|
||||
Spring Boot is "Spring for Snowboarders". If you are kewl, or just impatient, and you
|
||||
want to use Spring, then this is the place to be. Spring Boot is the code-name for a
|
||||
group of related technologies, that will get you up and running with
|
||||
Spring-powered, production-grade applications and services with absolute minimum fuss.
|
||||
It takes an opinionated view of the Spring family so that new and existing users can
|
||||
quickly get to the bits they need. Assumes limited knowledge of the Java development
|
||||
ecosystem. Absolutely no code generation and no XML (unless you really want it).
|
||||
|
||||
The goals are:
|
||||
|
||||
* Radically faster and widely accessible getting started experience for Spring
|
||||
development
|
||||
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)
|
||||
* First class support for REST-ful services, modern web applications, batch jobs, and
|
||||
enterprise integration
|
||||
* Applications that adapt their behavior or configuration to their environment
|
||||
* Optionally use Groovy features like DSLs and AST transformations to accelerate the
|
||||
implementation of basic business requirements
|
||||
* Absolutely no code generation and no requirement for XML configuration
|
||||
|
||||
## Quick Start Script Example
|
||||
The Spring Zero command line tool uses [Groovy](http://groovy.codehaus.org/) underneath
|
||||
so that we can present simple Spring snippets that can 'just run', for example:
|
||||
|
||||
```groovy
|
||||
@Controller
|
||||
class ThisWillActuallyRun {
|
||||
|
||||
@RequestMapping("/")
|
||||
@ResponseBody
|
||||
String home() {
|
||||
return "Hello World!"
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
$ spring run app.groovy
|
||||
$ curl localhost:8080
|
||||
Hello World!
|
||||
```
|
||||
|
||||
## Installing
|
||||
You need to [build from source](#building-from-source) for now, but when it's done
|
||||
instructions will look like this:
|
||||
_See [below](#installing-the-cli) for command line tool installation instructions._
|
||||
|
||||
1) Get Java. Download and install the Java SDK from [www.java.com](http://www.java.com)
|
||||
## Quick Start Java Example
|
||||
If you don't want to use the command line tool, or you would rather work using Java and
|
||||
an IDE you can. Just add a `main()` method that calls `SpringApplication` and
|
||||
add `@EnableAutoConfiguration`:
|
||||
|
||||
```java
|
||||
import org.springframework.boot.*;
|
||||
import org.springframework.boot.autoconfiguration.*;
|
||||
import org.springframework.stereotype.*;
|
||||
import org.springframework.web.bind.annotation.*;
|
||||
|
||||
2) Get Spring
|
||||
@Controller
|
||||
@EnableAutoConfiguration
|
||||
public class SampleController {
|
||||
|
||||
$ curl -s initializr.cfapps.io/installer | bash
|
||||
@RequestMapping("/")
|
||||
@ResponseBody
|
||||
String home() {
|
||||
return "Hello World!"
|
||||
}
|
||||
|
||||
public static void main(String[] args) throws Exception {
|
||||
SpringApplication.run(SampleController.class, args);
|
||||
}
|
||||
|
||||
or use the [Windows installer](#installing)
|
||||
}
|
||||
```
|
||||
|
||||
_NOTE: the above example assumes your build system has imported the `spring-starter-web` maven pom._
|
||||
|
||||
## Installing the CLI
|
||||
You need [Java SDK v1.6](http://www.java.com) or higher to run the command line tool. You
|
||||
should check your current Java installation before you begin:
|
||||
|
||||
$ java -version
|
||||
|
||||
Complete installation instructions TBD. For now you can
|
||||
[build from source](#building-from-source).
|
||||
|
||||
## Building from source
|
||||
Spring Zero can be [built with maven](http://maven.apache.org/run-maven/index.html) v3.0
|
||||
Spring Boot can be [built with maven](http://maven.apache.org/run-maven/index.html) v3.0
|
||||
or above.
|
||||
|
||||
$ mvn clean install
|
||||
|
||||
An `alias` can be used for the Spring Boot command line tool:
|
||||
You can use an `alias` for the Spring Boot command line tool:
|
||||
|
||||
$ alias spring="java -jar ~/.m2/repository/org/springframework/boot/spring-cli/0.5.0.BUILD-SNAPSHOT/spring-cli-0.5.0.BUILD-SNAPSHOT.jar"
|
||||
|
||||
_Also see [docs/CONTRIBUTING](docs/CONTRIBUTING.md) if you want to submit pull requests._
|
||||
_Also see [CONTRIBUTING.md] if you wish to submit pull requests._
|
||||
|
||||
## Spring Boot Modules
|
||||
There are a number of modules in Spring Boot. Here are the important ones:
|
||||
|
||||
## Quick Start Example
|
||||
The Spring Zero command line tool uses Groovy underneath so that we can present simple
|
||||
snippets that can just run, for example:
|
||||
|
||||
$ cat > app.groovy
|
||||
@Controller
|
||||
class ThisWillActuallyRun {
|
||||
@RequestMapping("/")
|
||||
@ResponseBody
|
||||
String home() {
|
||||
return "Hello World!"
|
||||
}
|
||||
}
|
||||
<ctrl-d>
|
||||
$ spring run app.groovy
|
||||
$ curl localhost:8080
|
||||
Hello World!
|
||||
### 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.
|
||||
|
||||
If you don't want to use the command line tool, or you would rather work using Java and
|
||||
an IDE you can. Just add a `main()` method that calls `SpringApplication` and
|
||||
add `@EnableAutoConfiguration`:
|
||||
_See [spring-boot/README.md](spring-boot/README.md)._
|
||||
|
||||
import org.springframework.stereotype.*;
|
||||
import org.springframework.web.bind.annotation.*;
|
||||
import org.springframework.boot.context.annotation.*;
|
||||
|
||||
@Controller
|
||||
@EnableAutoConfiguration
|
||||
public class SampleController {
|
||||
### 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.
|
||||
|
||||
@RequestMapping("/")
|
||||
@ResponseBody
|
||||
String home() {
|
||||
return "Hello World!"
|
||||
}
|
||||
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.
|
||||
|
||||
public static void main(String[] args) throws Exception {
|
||||
SpringApplication.run(SampleController.class, args);
|
||||
}
|
||||
_See [spring-boot-autoconfigure/README.md](spring-boot-autoconfigure/README.md)._
|
||||
|
||||
}
|
||||
|
||||
_NOTE: the above example assumes your build system has imported the `spring-starter-web`
|
||||
maven pom._
|
||||
### 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 Components
|
||||
There are a number of components in Boot. Here are the important ones:
|
||||
|
||||
### The Spring CLI
|
||||
The 'spring' command line application compiles and runs Groovy source, making it super
|
||||
### 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-cli/README](spring-cli/README.md).*
|
||||
|
||||
|
||||
### Spring Boot
|
||||
The main library providing features that support the other parts of Spring Boot.
|
||||
Features include:
|
||||
|
||||
* `SpringApplication` - a class with static convenience methods that make it really easy
|
||||
to write a standalone 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
|
||||
|
||||
_See [spring-boot/README](spring-boot/README.md)._
|
||||
|
||||
*See [spring-boot-cli/README.md](spring-boot-cli/README.md).*
|
||||
|
||||
### Spring Autoconfigure
|
||||
Spring Zero can configure large parts of common applications based on detecting the
|
||||
content of the classpath and any existing application context. A single
|
||||
`@EnableAutoConfigure` annotation triggers auto-configuration of the Spring context.
|
||||
|
||||
Auto-configuration attempts to guess what beans a user might want based on their
|
||||
classpath. For example, If a 'HSQLDB' is on the classpath the user probably wants an
|
||||
in-memory database to be defined. Auto-configuration will back away as the user starts
|
||||
to define their own beans.
|
||||
|
||||
_See [spring-autoconfigure/README](spring-autoconfigure/README.md)._
|
||||
|
||||
|
||||
### Spring Actuator
|
||||
Spring Actuator uses auto-configuration to decorate your application with features that
|
||||
### spring-boot-ops
|
||||
Ops uses 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-actuator/README](spring-actuator/README.md)._
|
||||
|
||||
switch off the built in features, or extend or replace them, it makes that really easy as
|
||||
well.
|
||||
|
||||
### Spring Starters
|
||||
Spring 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 one dependency in your project, and you are good to go.
|
||||
_See [spring-boot-ops/README.md](spring-boot-ops/README.md)._
|
||||
|
||||
_See [spring-starters/README](spring-starters/README.md)._
|
||||
|
||||
### spring-boot-loader
|
||||
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-gradle-plugin/README.md) or
|
||||
[Maven](spring-boot-maven-plugin/README.md) plugin.
|
||||
|
||||
### Packaging
|
||||
The [spring-launcher](spring-launcher/) and
|
||||
[spring-maven-packaging-plugin](spring-maven-packaging-plugin) provide a convenient way
|
||||
to package you application for release. Applications can be released as a single jar
|
||||
file that can simply be launched using `java -jar`.
|
||||
|
||||
_See [spring-launcher/README](spring-launcher/README.md) &
|
||||
[spring-package-maven-plugin/README](spring-package-maven-plugin/README.md)._
|
||||
_See [spring-boot-loader/README.md](spring-boot-loader/README.md)._
|
||||
|
||||
|
||||
## Samples
|
||||
Groovy samples for use with the command line application are available in
|
||||
[spring-cli/samples](spring-cli/samples/#). To run the CLI samples type
|
||||
[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-sample](spring-boot-samples/#) and should
|
||||
be build with maven and run use `java -jar target/<sample>.jar`. The following java
|
||||
Java samples are available in [spring-boot-samples](spring-boot-samples/#) and should
|
||||
be build with maven and run use `java -jar target/<sample>.jar`. The following java
|
||||
samples are provided:
|
||||
|
||||
* spring-boot-sample-simple - A simple command line application
|
||||
* spring-boot-sample-tomcat - Embedded Tomcat
|
||||
* spring-boot-sample-jetty - Embedded Jetty
|
||||
* spring-boot-sample-actuator - Simple REST service with production features
|
||||
* spring-boot-sample-actuator-ui - A web UI example with production features
|
||||
* spring-boot-sample-web-ui - A thymeleaf web application
|
||||
* spring-sample-batch - Define and run a Batch job in a few lines of code
|
||||
* spring-sample-data-jpa - Spring Data JPA + Hibernate + HSQLDB
|
||||
* spring-boot-sample-integration - A spring integration application
|
||||
* spring-boot-sample-profile - example showing Spring's `@profile` support
|
||||
* spring-boot-sample-traditional - shows Spring Zero with more traditional WAR packaging
|
||||
* [spring-boot-sample-simple](spring-boot-sample-simple) - A simple command line application
|
||||
* [spring-boot-sample-tomcat](spring-boot-sample-tomcat) - Embedded Tomcat
|
||||
* [spring-boot-sample-jetty](spring-boot-sample-jetty) - Embedded Jetty
|
||||
* [spring-boot-sample-ops](spring-boot-sample-ops) - Simple REST service with production features
|
||||
* [spring-boot-sample-ops-ui](spring-boot-sample-ops-ui) - A web UI example with production features
|
||||
* [spring-boot-sample-web-ui](spring-boot-sample-web-ui) - A thymeleaf web application
|
||||
* [spring-boot-sample-web-static](spring-boot-sample-web-static) - A web application service static files
|
||||
* [spring-sample-batch](spring-sample-batch) - Define and run a Batch job in a few lines of code
|
||||
* [spring-sample-data-jpa](spring-sample-data-jpa) - Spring Data JPA + Hibernate + HSQLDB
|
||||
* [spring-boot-sample-integration](spring-boot-sample-integration) - A spring integration application
|
||||
* [spring-boot-sample-profile](spring-boot-sample-profile) - example showing Spring's `@profile` support
|
||||
* [spring-boot-sample-traditional](spring-boot-sample-traditional) - shows more traditional WAR packaging
|
||||
(but also executable using `java -jar`)
|
||||
* spring-boot-sample-xml - Example show how Spring Boot can be mixed with traditional XML
|
||||
configuration
|
||||
|
||||
* [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)
|
||||
|
||||
@ -0,0 +1,153 @@
|
||||
# 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. For more in depth coverage of the features
|
||||
of Spring Boot.Strap, go to the [Feature Guide](docs/Features.md).
|
||||
|
||||
# Getting Started
|
||||
|
||||
You will need Java (6 at least) and a build tool (Maven is what we use
|
||||
below, but you are more than welcome to use gradle). These can be
|
||||
downloaded or installed easily in most operating systems. For Ubuntu:
|
||||
|
||||
$ sudo apt-get install openjdk-6-jdk maven
|
||||
|
||||
<!--FIXME: short instructions for Mac.-->
|
||||
|
||||
## A basic project
|
||||
|
||||
If you are using Maven create a really simple `pom.xml` with 2 dependencies:
|
||||
|
||||
`pom.xml`
|
||||
|
||||
```
|
||||
<project>
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<groupId>com.mycompany</groupId>
|
||||
<artifactId>myproject</artifactId>
|
||||
<version>1.0.0-SNAPSHOT</version>
|
||||
<packaging>jar</packaging>
|
||||
<properties>
|
||||
<start-class>com.mycompany.Application</start-class>
|
||||
</properties>
|
||||
<parent>
|
||||
<groupId>org.springframework.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, and read more in the
|
||||
[Feature Guide](docs/Features.md).
|
||||
Loading…
Reference in New Issue