Skip to content

S
spring-boot
Commit 9cf59050 authored by Phillip Webb's avatar Phillip Webb
Browse files
Options

Documentation

parent ec36efd5
Expand all Show whitespace changes
Inline Side-by-side
Showing with 370 additions and 274 deletions
docs/CONTRIBUTING.md → CONTRIBUTING.md
View file @ 9cf59050
...@@ -3,7 +3,6 @@ Spring Boot is released under the non-restrictive Apache 2.0 license. If you wou ...@@ -3,7 +3,6 @@ Spring Boot is released under the non-restrictive Apache 2.0 license. If you wou
to contribute something, or simply want to hack on the code this document should help to contribute something, or simply want to hack on the code this document should help
you get started. you get started.
## Working with the code ## Working with the code
If you don't have an IDE preference we would recommend that you use If you don't have an IDE preference we would recommend that you use
[Spring Tools Suite](http://www.springsource.com/developer/sts) or [Spring Tools Suite](http://www.springsource.com/developer/sts) or
...@@ -11,7 +10,6 @@ If you don't have an IDE preference we would recommend that you use ...@@ -11,7 +10,6 @@ If you don't have an IDE preference we would recommend that you use
[m2eclipe](http://eclipse.org/m2e/) eclipse plugin for maven support. Other IDEs [m2eclipe](http://eclipse.org/m2e/) eclipse plugin for maven support. Other IDEs
and tools should also work without issue. and tools should also work without issue.
### Building from source ### Building from source
To build the source you will need to install To build the source you will need to install
[Apache Maven](http://maven.apache.org/run-maven/index.html) v3.0 or above. The project [Apache Maven](http://maven.apache.org/run-maven/index.html) v3.0 or above. The project
...@@ -24,7 +22,6 @@ to submit a pull request: ...@@ -24,7 +22,6 @@ to submit a pull request:
$ mvn clean install -DskipTests $ mvn clean install -DskipTests
### Importing into eclipse with m2eclipse ### Importing into eclipse with m2eclipse
We recommend the [m2eclipe](http://eclipse.org/m2e/) eclipse plugin when working with We recommend the [m2eclipe](http://eclipse.org/m2e/) eclipse plugin when working with
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
...@@ -47,7 +44,6 @@ With the requisite eclipse plugins installed you can select ...@@ -47,7 +44,6 @@ With the requisite eclipse plugins installed you can select
`import existing maven projects` from the `file` menu to import the code. You will `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. 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 If you prefer not to use m2eclipse you can generate eclipse project meta-data using the
following command: following command:
...@@ -60,13 +56,10 @@ from the `file` menu. ...@@ -60,13 +56,10 @@ 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. 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
The sample application are used as integration tests during the build `mvn install`). Due to the fact that they make use of the `spring-boot-maven-plugin`
(when you `mvn install`). Due to the fact that they make use of the they cannot be called directly, and so instead are launched via the
`spring-package-maven-plugin` they cannot be called directly, and so `maven-invoker-plugin`. If you encounter build failures running the integration tests,
instead are launched via the `maven-invoker-plugin`. If you encounter check the `build.log` file in the appropriate sample directory.
build failures running the integration tests, check the `build.log`
file in the appropriate sample directory.
README.md
View file @ 9cf59050
This diff is collapsed.
docs/SCRAPBOOK.md 0 → 100644
View file @ 9cf59050
# 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).
\ No newline at end of file
spring-boot/README.md
View file @ 9cf59050
# Spring Boot.Strap # Spring Boot
Spring Boot provides the central features for the other modules in the project. It is
Spring Boot.Strap provides features for the other parts of Spring relatively unopinionated and it has minimal dependencies which makes it usable as a
Boot. It is relatively unopinionated and therefore usable as a stand-alone library for anyone whose tastes diverge from ours.
standalone library for anyone whose tastes diverge from ours.
## SpringApplication
|Feature |Implementation |Notes | 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
|Launch Spring from Java main |SpringApplication | Plenty of convenience methods and customization opportunities | to the static `SpringApplication.run` method:
|Server |Tomcat or Jetty | |
|Logging |Logback, Log4j or JDK | Sensible defaults configurations. | ```java
|Externalized configuration | Properties or YAML | Support for Spring profiles. Bind automatically to @Bean. | public static void main(String[] args) {
SpringApplication.run(SpringConfiguration.class, args);
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 When you application starts you should see something similar to the following:
<!--FIXME: short instructions for Mac.--> ```
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
Spring Boot (v0.5.0.BUILD-SNAPSHOT)
## A basic project 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
```
If you are using Maven create a really simple `pom.xml` with 2 dependencies: By default `INFO` logging messages will shown, including some relevant startup information
such as the user that started the application.
`pom.xml` ### 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(SpringConfiguration.class);
app.setShowBanner(false);
app.run(args);
}
``` ```
<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 See the `SpringApplication` Javadoc for a complete list of the configuration options
`Application.java` ### Accessing command line properties
``` By default `SpringApplication` will expose any command line arguments as Spring
package com.mycompany; Properties. This allows you to easily access arguments using by injecting them
as `@Values`
import org.springframework.boot.SpringApplication; ```java
import org.springframework.context.annotation.Configuration; import org.springframework.stereotype.*
import org.springframework.beans.factory.annotation.*
@Configuration @Component
public class Application { public class MyBean {
public static void main(String[] args) { @Value("${name}")
SpringApplication.run(Application.class, args); private String name;
} // Running 'java -jar myapp.jar --name=Spring' will set this to "Spring"
// ...
} }
``` ```
You should be able to run it already: ### CommandLineRunner beans
If you wan't 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 the interface.
$ mvn package ```java
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar import org.springframework.boot.*
import org.springframework.stereotype.*
. ____ _ __ _ _ @Component
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ public class MyBean implements CommandLineRunner {
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
Spring Bootstrap
2013-07-19 17:13:51.673 INFO 18937 --- [ main] com.mycompany.Application ... public void run(String... args) {
... <logs showing application starting up> // Do something...
}
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; You can additionally implement the `org.springframework.core.Ordered` interface or use
the `org.springframework.core.annotation.Order` annotation if serveral `CommandLineRunner`
beans are defined that must be called in a specific order.
@Override ### Application Exit
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) { ## Embedded Servlet Container Support
this.message = message;
}
}
```
The `@ConfigurationProperties` annotation binds the Spring ## External Configuration
`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:
``` ## Conditionals
$ mvn package
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar --message="Hello World" ## ApplicationContextInitializers
...
Hello World
```
To add more features, add some `@Bean` definitions to your
`Application` class, and read more in the
[Feature Guide](docs/Features.md).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment