Phillip Webb
13 years ago
4 changed files with 370 additions and 274 deletions
@ -1,188 +1,190 @@
@@ -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 @@
@@ -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