@ -17,47 +17,50 @@ Our primary goals are:
@@ -17,47 +17,50 @@ Our primary goals are:
(e.g. embedded servers, security, metrics, health checks, externalized configuration)
* Absolutely no code generation and no requirement for XML configuration
## Installing the CLI
The Spring Boot command line tool uses
[Groovy ](http://groovy.codehaus.org/ ) underneath so that we can
present simple Spring snippets that can 'just run'. You don't need
the CLI to get started (see the
[Java example ](#quick-start-java-example ) below), but it's the
quickest way to get a Spring application off the ground. 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:
## 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.
$ java -version
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.
### MacOS with Brew
### Installing the CLI
> **Note:** If you don't want to use the CLI,
> [jump ahead to the Java example ](#quick-start-java-example ).
If you are on a Mac and using [homebrew ](http://brew.sh/ ), all you need do to install the Spring Boot CLI is:
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:
$ brew install spring-boot-cli
$ java -version
It will install `/usr/local/bin/spring` . Now you can jump right to a [quick start example ](#quick-start-groovy-example ).
### Manual installation
You can download the Spring CLI distribution from the Spring software repository:
> **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
* [spring-boot-cli-0.5.0.BUILD-SNAPSHOT-bin.zip ](http://repo.springframework.org/milestone/org/springframework/boot/spring-boot-cli/0.5.0.M1/spring-boot-cli-0.5.0.M1-bin.zip )
* [spring-boot-cli-0.5.0.BUILD-SNAPSHOT-bin.tar.gz ](http://repo.springframework.org/milestone/org/springframework/boot/spring-boot-cli/0.5.0.M1/spring-boot-cli-0.5.0.M1-bin.tar.gz )
### Cross Platform `java - jar`
An alternative way to install Spring Boot CLI is to downloaded it from our Maven repository, and then you can use a shell `alias` :
Cutting edge [snapshot distributions ](http://repo.springframework.org/snapshot/org/springframework/boot/spring-boot-cli/ )
are also available.
$ wget http://maven.springframework.org/milestone/org/springframework/boot/spring-boot-cli/0.5.0.M1/spring-boot-cli-0.5.0.M1.jar
$ alias spring="java -jar `pwd` /spring-boot-cli-0.5.0.M1.jar"
Once downloaded, follow the [INSTALL ](spring-boot-cli/src/main/content/INSTALL.txt )
instructions from the unpacked archive.
If you don't have `wget` installed on your system you might have
`curl` (with `-o` for setting the output filename). Windows users
will need [cygwin ](http://www.cygwin.org ) to use the `alias` command,
but they can run `java -jar` directly and that will work.
### 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 spring-boot-cli
Complete installation including a downloadable `.zip` with a shell
script TBD .
Homebrew will install `spring` to `/usr/local/bin` . Now you can jump right to a
[quick start example ](#quick-start-script-example ) .
< a name = "quick-start-groovy-example" > < / a >
## 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
@ -76,70 +79,95 @@ class ThisWillActuallyRun {
@@ -76,70 +79,95 @@ class ThisWillActuallyRun {
Then run it from a shell:
```
$ spring run app.groovy --verbose
$ curl localhost:8080
Hello World!
$ spring run app.groovy
```
It might take a few minutes the first time you do this while some
dependencies are downloaded (which is why we added the `--verbose`
option - you can remove that if you prefer). If you are a maven user
and have a fully loaded local cache with all the required dependencies
you will find it is much faster.
> **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!
< span id = "quick-start-java-example" / >
## Quick Start Java Example
## 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. Create a `pom.xml` (or the equivalent with your favourite build system):
an IDE you can. Here is how you build the same example using Java.
`pom.xml`
### 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 xsi:schemaLocation = "http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns = "http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance ">
< 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 > 0.5.0.M1< / 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 > ${project.groupId} < / groupId >
< groupId > org.springframework.boot < / groupId >
< artifactId > spring-boot-maven-plugin< / artifactId >
< / plugin >
< / plugins >
< / build >
<!-- TODO: remove once Spring Boot is in Maven Central -->
<!-- Allow access to Spring milestones and snapshots -->
<!-- (you don't need this if you are using the GA release) -->
< repositories >
< repository >
< id > spring-milestone< / id >
< id > spring-snapshots< / id >
< url > http://repo.springsource.org/snapshot< / url >
< snapshots > < enabled > true< / enabled > < / snapshots >
< / repository >
< repository >
< id > spring-milestones< / id >
< url > http://repo.springsource.org/milestone< / url >
< snapshots > < enabled > true< / enabled > < / snapshots >
< / repository >
< / repositories >
< pluginRepositories >
< pluginRepository >
< id > spring-milestone< / id >
< id > spring-snapshots< / id >
< url > http://repo.springsource.org/snapshot< / url >
< / pluginRepository >
< pluginRepository >
< id > spring-milestones< / id >
< url > http://repo.springsource.org/milestone< / url >
< / pluginRepository >
< / pluginRepositories >
< / project >
```
Then just add a class in `src/main/java` with a `main()` method that
calls `SpringApplication` and add `@EnableAutoConfiguration` , e.g:
> **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.
`src/main/java/SampleController.java`
### 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.*;
@ -163,23 +191,36 @@ public class SampleController {
@@ -163,23 +191,36 @@ public class SampleController {
}
```
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
... Spring starting up ...
```
and in anonther terminal:
Open [http://localhost:8080 ](http://localhost:8080 ) in your favorite web browser and you
should see the following output:
> Hello World!
```
$ curl localhost:8080
Hello World!
```
## Building Spring Boot from source
You don't need to build from source to use Spring Boot (it's in
[repo.springsource.org ](http://repo.springsource.org )), 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.
## Spring Boot Modules
There are a number of modules in Spring Boot. Here are the important ones:
$ mvn clean install
_Also see [CONTRIBUTING.md ](CONTRIBUTING.md ) if you wish to submit pull requests._
## Further Reading
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,
@ -191,24 +232,22 @@ these include:
@@ -191,24 +232,22 @@ these include:
* 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.
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,
`HSQLDB`
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
@ -219,7 +258,6 @@ project, and you are good to go.
@@ -219,7 +258,6 @@ 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
@ -227,7 +265,6 @@ can also watch files, automatically recompiling and restarting when they change.
@@ -227,7 +265,6 @@ 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
@ -238,17 +275,15 @@ makes that really easy as well.
@@ -238,17 +275,15 @@ 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
`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
@ -287,13 +322,4 @@ samples are provided:
@@ -287,13 +322,4 @@ samples are provided:
Example show how Spring Boot can be mixed with traditional XML configuration (we
generally recommend using Java `@Configuration` whenever possible)
## Building Spring Boot from source You don't need to build from
source to use Spring Boot (it's in the Maven repositories), 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
or above.
$ mvn clean install
_Also see [CONTRIBUTING.md ](CONTRIBUTING.md ) if you wish to submit pull requests._
Phillip Webb
13 years ago