Phillip Webb
13 years ago
4 changed files with 370 additions and 274 deletions
@ -1,188 +1,190 @@ |
|||||||
# Spring Boot |
# Spring Boot |
||||||
Spring Boot is "Spring for Snowboarders". If you are kewl, or just impatient, and you |
Spring Boot makes it easy to create Spring-powered, production-grade applications and |
||||||
want to use Spring, then this is the place to be. Spring Boot is the code-name for a |
services with absolute minimum fuss. It takes an opinionated view of the Spring platform |
||||||
group of related technologies, that will get you up and running with |
so that new and existing users can quickly get to the bits they need. |
||||||
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 |
You can use Spring Boot to create stand-alone Java applications that can be started using |
||||||
quickly get to the bits they need. Assumes limited knowledge of the Java development |
`java -jar` or more traditional WAR deployments. We also provide a command line tool |
||||||
ecosystem. Absolutely no code generation and no XML (unless you really want it). |
that runs spring scripts. |
||||||
|
|
||||||
The goals are: |
Our primary goals are: |
||||||
|
|
||||||
* Radically faster and widely accessible getting started experience for Spring |
* Provide a radically faster and widely accessible getting started experience for all |
||||||
development |
Spring development |
||||||
* Be opinionated out of the box, but get out of the way quickly as requirements start to |
* Be opinionated out of the box, but get out of the way quickly as requirements start to |
||||||
diverge from the defaults |
diverge from the defaults |
||||||
* Provide a range of non-functional features that are common to large classes of projects |
* 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) |
(e.g. embedded servers, security, metrics, health checks, externalized configuration) |
||||||
* First class support for REST-ful services, modern web applications, batch jobs, and |
* Absolutely no code generation and no requirement for XML configuration |
||||||
enterprise integration |
|
||||||
* Applications that adapt their behavior or configuration to their environment |
## Quick Start Script Example |
||||||
* Optionally use Groovy features like DSLs and AST transformations to accelerate the |
The Spring Zero command line tool uses [Groovy](http://groovy.codehaus.org/) underneath |
||||||
implementation of basic business requirements |
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 |
_See [below](#installing-the-cli) for command line tool installation instructions._ |
||||||
You need to [build from source](#building-from-source) for now, but when it's done |
|
||||||
instructions will look like this: |
|
||||||
|
|
||||||
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 |
## 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. |
or above. |
||||||
|
|
||||||
$ mvn clean install |
$ 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" |
$ 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 |
### spring-boot |
||||||
The Spring Zero command line tool uses Groovy underneath so that we can present simple |
The main library providing features that support the other parts of Spring Boot, |
||||||
snippets that can just run, for example: |
these include: |
||||||
|
|
||||||
$ cat > app.groovy |
|
||||||
@Controller |
|
||||||
class ThisWillActuallyRun { |
|
||||||
@RequestMapping("/") |
|
||||||
@ResponseBody |
|
||||||
String home() { |
|
||||||
return "Hello World!" |
|
||||||
} |
|
||||||
} |
|
||||||
<ctrl-d> |
|
||||||
$ spring run app.groovy |
|
||||||
$ curl localhost:8080 |
|
||||||
Hello World! |
|
||||||
|
|
||||||
|
* 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 |
_See [spring-boot/README.md](spring-boot/README.md)._ |
||||||
an IDE you can. Just add a `main()` method that calls `SpringApplication` and |
|
||||||
add `@EnableAutoConfiguration`: |
|
||||||
|
|
||||||
import org.springframework.stereotype.*; |
|
||||||
import org.springframework.web.bind.annotation.*; |
|
||||||
import org.springframework.boot.context.annotation.*; |
|
||||||
|
|
||||||
@Controller |
### spring-boot-autoconfigure |
||||||
@EnableAutoConfiguration |
Spring Boot can configure large parts of common applications based on the content |
||||||
public class SampleController { |
of their classpath. A single `@EnableAutoConfiguration` annotation triggers |
||||||
|
auto-configuration of the Spring context. |
||||||
|
|
||||||
@RequestMapping("/") |
Auto-configuration attempts to deduce which beans a user might need. For example, If |
||||||
@ResponseBody |
'HSQLDB' is on the classpath, and the user has not configured any database connections, |
||||||
String home() { |
then they probably want an in-memory database to be defined. Auto-configuration will |
||||||
return "Hello World!" |
always back away as the user starts to define their own beans. |
||||||
} |
|
||||||
|
|
||||||
public static void main(String[] args) throws Exception { |
_See [spring-boot-autoconfigure/README.md](spring-boot-autoconfigure/README.md)._ |
||||||
SpringApplication.run(SampleController.class, args); |
|
||||||
} |
|
||||||
|
|
||||||
} |
|
||||||
|
|
||||||
_NOTE: the above example assumes your build system has imported the `spring-starter-web` |
### spring-boot-starters |
||||||
maven pom._ |
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 |
### spring-boot-cli |
||||||
The 'spring' command line application compiles and runs Groovy source, making it super |
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 |
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. |
can also watch files, automatically recompiling and restarting when they change. |
||||||
|
|
||||||
*See [spring-cli/README](spring-cli/README.md).* |
*See [spring-boot-cli/README.md](spring-boot-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)._ |
|
||||||
|
|
||||||
|
|
||||||
### 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 |
### spring-boot-ops |
||||||
classpath. For example, If a 'HSQLDB' is on the classpath the user probably wants an |
Ops uses auto-configuration to decorate your application with features that |
||||||
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 |
|
||||||
make it instantly deployable and supportable in production. For instance if you are |
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 |
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 |
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. |
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)._ |
|
||||||
|
|
||||||
|
|
||||||
### Spring Starters |
_See [spring-boot-ops/README.md](spring-boot-ops/README.md)._ |
||||||
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-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 |
_See [spring-boot-loader/README.md](spring-boot-loader/README.md)._ |
||||||
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)._ |
|
||||||
|
|
||||||
|
|
||||||
## Samples |
## Samples |
||||||
Groovy samples for use with the command line application are available in |
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. |
`spring run <sample>.groovy` from samples directory. |
||||||
|
|
||||||
Java samples are available in [spring-boot-sample](spring-boot-samples/#) and should |
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 |
be build with maven and run use `java -jar target/<sample>.jar`. The following java |
||||||
samples are provided: |
samples are provided: |
||||||
|
|
||||||
* spring-boot-sample-simple - A simple command line application |
* [spring-boot-sample-simple](spring-boot-sample-simple) - A simple command line application |
||||||
* spring-boot-sample-tomcat - Embedded Tomcat |
* [spring-boot-sample-tomcat](spring-boot-sample-tomcat) - Embedded Tomcat |
||||||
* spring-boot-sample-jetty - Embedded Jetty |
* [spring-boot-sample-jetty](spring-boot-sample-jetty) - Embedded Jetty |
||||||
* spring-boot-sample-actuator - Simple REST service with production features |
* [spring-boot-sample-ops](spring-boot-sample-ops) - Simple REST service with production features |
||||||
* spring-boot-sample-actuator-ui - A web UI example 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 - A thymeleaf web application |
* [spring-boot-sample-web-ui](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-boot-sample-web-static](spring-boot-sample-web-static) - A web application service static files |
||||||
* spring-sample-data-jpa - Spring Data JPA + Hibernate + HSQLDB |
* [spring-sample-batch](spring-sample-batch) - Define and run a Batch job in a few lines of code |
||||||
* spring-boot-sample-integration - A spring integration application |
* [spring-sample-data-jpa](spring-sample-data-jpa) - Spring Data JPA + Hibernate + HSQLDB |
||||||
* spring-boot-sample-profile - example showing Spring's `@profile` support |
* [spring-boot-sample-integration](spring-boot-sample-integration) - A spring integration application |
||||||
* spring-boot-sample-traditional - shows Spring Zero with more traditional WAR packaging |
* [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`) |
(but also executable using `java -jar`) |
||||||
* spring-boot-sample-xml - Example show how Spring Boot can be mixed with traditional XML |
* [spring-boot-sample-xml](spring-boot-sample-xml) - Example show how Spring Boot can be mixed with traditional |
||||||
configuration |
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