mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-07-05 00:56:58 +08:00
Start to breakup README.md documentation
This commit is contained in:
parent
30bf5dcb0d
commit
14aa163731
70
CONTRIBUTING.md
Normal file
70
CONTRIBUTING.md
Normal file
@ -0,0 +1,70 @@
|
|||||||
|
# Contributing to Spring Zero
|
||||||
|
Spring Zero is released under the non-restrictive Apache 2.0 license. If you would like
|
||||||
|
to contribute something, or simply want to hack on the code this document should help
|
||||||
|
you get started.
|
||||||
|
|
||||||
|
|
||||||
|
## Working with the code
|
||||||
|
If you don't have an IDE preference we would recommend that you use
|
||||||
|
[Spring Tools Suite](http://www.springsource.com/developer/sts) or
|
||||||
|
[Eclipse](http://eclipse.org) when working with the code. We use the
|
||||||
|
[m2eclipe](http://eclipse.org/m2e/) eclipse plugin for maven support. Other IDEs
|
||||||
|
and tools should also work without issue.
|
||||||
|
|
||||||
|
|
||||||
|
### Building from source
|
||||||
|
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
|
||||||
|
can be build using the standard maven command:
|
||||||
|
|
||||||
|
$ mvn clean install
|
||||||
|
|
||||||
|
If you are rebuilding often, you might also want to skip the tests until you are ready
|
||||||
|
to submit a pull request:
|
||||||
|
|
||||||
|
$ mvn clean install -DskipTests
|
||||||
|
|
||||||
|
|
||||||
|
### Importing into eclipse with m2eclipse
|
||||||
|
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
|
||||||
|
marketplace".
|
||||||
|
|
||||||
|
Spring Zero includes project specific source formatting settings, in order to have these
|
||||||
|
work with m2eclipse, we provide an additional eclipse plugin that you can install:
|
||||||
|
|
||||||
|
* Select `Install new software` from the `help` menu
|
||||||
|
* Click `Add...` to add a new repository
|
||||||
|
* Click the `Archive...` button
|
||||||
|
* Select `org.eclipse.m2e.maveneclipse.site-0.0.1-SNAPSHOT-site.zip`
|
||||||
|
from the `eclipse` folder in this checkout
|
||||||
|
* Install "Maven Integration for the maven-eclipse-plugin"
|
||||||
|
|
||||||
|
_NOTE: This plugin is optional. Projects can be imported without the plugin, your code
|
||||||
|
changes just won't be automatically formatted._
|
||||||
|
|
||||||
|
With the requisite eclipse plugins installed you can select
|
||||||
|
`import existing maven projects` from the `file` menu to import the code. You will
|
||||||
|
need to import the root `spring-zero` pom and the `spring-zero-samples` pom separately.
|
||||||
|
|
||||||
|
|
||||||
|
### Importing into eclipse without m2eclipse
|
||||||
|
If you prefer not to use m2eclipse you can generate eclipse project meta-data using the
|
||||||
|
following command:
|
||||||
|
|
||||||
|
$ mvn eclipse:eclipse
|
||||||
|
|
||||||
|
The generated eclipse projects can be imported by selecting `import existing projects`
|
||||||
|
from the `file` menu.
|
||||||
|
|
||||||
|
### Importing into other IDEs
|
||||||
|
Maven is well supported by most Java IDEs. Refer to you vendor documentation.
|
||||||
|
|
||||||
|
|
||||||
|
### Integration tests
|
||||||
|
The sample application are used as integration tests during the build. Due to the
|
||||||
|
fact that they make use of the `spring-package-maven-plugin` they cannot be called
|
||||||
|
directly, and so instead are launched via the `maven-invoker-plugin`. If you encounter
|
||||||
|
build failures running the integration tests, check the `build.log` file in the appropriate
|
||||||
|
sample directory.
|
||||||
|
|
246
README.md
246
README.md
@ -1,45 +1,57 @@
|
|||||||
# Spring Zero
|
# Spring Zero
|
||||||
|
Spring Zero is "Spring for Snowboarders". If you are kewl, or just impatient, and you
|
||||||
Spring Zero is "Spring for Snowboarders". If you are kewl, or
|
want to use Spring, then this is the place to be. Spring Zero is the code-name for a
|
||||||
just impatient, and you want to use Spring, then this is the place to
|
group of related technologies, that will get you up and running with
|
||||||
be. Spring Zero is a toolkit and runtime platform that will get
|
Spring-powered, production-grade applications and services with absolute minimum fuss.
|
||||||
you up and running with Spring-powered, production-grade applications
|
It takes an opinionated view of the Spring family so that new and existing users can
|
||||||
and services with absolute minimum fuss. It takes an opinionated view
|
quickly get to the bits they need. Assumes limited knowledge of the Java development
|
||||||
of the Spring family so that new and existing users can quickly get to
|
ecosystem. Absolutely no code generation and no XML (unless you really want it).
|
||||||
the bits they need. Assumes no knowledge of the Java development
|
|
||||||
ecosystem. Absolutely no code generation and no XML (unless you really
|
|
||||||
want it).
|
|
||||||
|
|
||||||
The goals are:
|
The goals are:
|
||||||
|
* Radically faster and widely accessible getting started experience for 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
|
||||||
|
|
||||||
|
|
||||||
* Radically faster and widely accessible getting started experience
|
|
||||||
for 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 behaviour or configuration to their
|
|
||||||
environment
|
|
||||||
* Optionally use Groovy features like DSLs and AST transformations to
|
|
||||||
accelerate the implementation of basic business requirements
|
|
||||||
|
|
||||||
## Installing
|
## Installing
|
||||||
You need to build from source for now, but when it's done instructions will look like this:
|
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
|
1) Get Java. Download and install the Java SDK from [www.java.com](http://www.java.com)
|
||||||
|
|
||||||
2) Get Spring
|
2) Get Spring
|
||||||
|
|
||||||
$ curl -s spring.cfapps.io/installer | bash
|
$ curl -s spring.cfapps.io/installer | bash
|
||||||
|
|
||||||
or use the Windows installer
|
|
||||||
|
|
||||||
3) Get to Work!
|
or use the [Windows installer](#installing)
|
||||||
|
|
||||||
$ cat > app.groovy
|
|
||||||
|
## Building from source
|
||||||
|
Spring Zero 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 Zero command line tool:
|
||||||
|
|
||||||
|
$ alias spr="java -jar ~/.m2/repository/org/springframework/zero/spring-cli/0.5.0.BUILD-SNAPSHOT/spring-cli-0.5.0.BUILD-SNAPSHOT.jar"
|
||||||
|
|
||||||
|
_Also see [CONTRIBUTING.md](/CONTRIBUTING.md) if you want to submit pull requests._
|
||||||
|
|
||||||
|
|
||||||
|
## 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
|
@Controller
|
||||||
class ThisWillActuallyRun {
|
class ThisWillActuallyRun {
|
||||||
@RequestMapping("/")
|
@RequestMapping("/")
|
||||||
@ -48,30 +60,24 @@ You need to build from source for now, but when it's done instructions will look
|
|||||||
return "Hello World!"
|
return "Hello World!"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
$ spring run app.groovy
|
<ctrl-d>
|
||||||
$ curl localhost:8080
|
$ spr run app.groovy
|
||||||
Hello World!
|
$ curl localhost:8080
|
||||||
|
Hello World!
|
||||||
|
|
||||||
|
|
||||||
## What? It's Groovy then? or like Grails? or Roo?
|
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
|
||||||
There is a command line tool that uses Groovy underneath so that we
|
add `@EnableAutoConfiguration`:
|
||||||
can present simple snippets that can just run just like the slimline
|
|
||||||
`app.groovy` example above. Groovy makes this really easy.
|
|
||||||
|
|
||||||
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`:
|
|
||||||
|
|
||||||
|
|
||||||
import org.springframework.stereotype.*;
|
import org.springframework.stereotype.*;
|
||||||
import org.springframework.web.bind.annotation.*;
|
import org.springframework.web.bind.annotation.*;
|
||||||
import org.springframework.bootstrap.context.annotation.*;
|
import org.springframework.bootstrap.context.annotation.*;
|
||||||
|
|
||||||
@Controller
|
@Controller
|
||||||
@EnableAutoConfiguration
|
@EnableAutoConfiguration
|
||||||
public class SampleController {
|
public class SampleController {
|
||||||
|
|
||||||
@RequestMapping("/")
|
@RequestMapping("/")
|
||||||
@ResponseBody
|
@ResponseBody
|
||||||
String home() {
|
String home() {
|
||||||
@ -81,109 +87,101 @@ calls `SpringApplication` and add `@EnableAutoConfiguration`:
|
|||||||
public static void main(String[] args) throws Exception {
|
public static void main(String[] args) throws Exception {
|
||||||
SpringApplication.run(SampleController.class, args);
|
SpringApplication.run(SampleController.class, args);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
_NOTE: the above example assumes your build system has imported the `spring-starter-web`
|
||||||
|
maven pom._
|
||||||
|
|
||||||
}
|
|
||||||
|
|
||||||
## Spring Zero Themes
|
## Spring Zero Components
|
||||||
|
There are a number of components in Zero. Here are the important ones:
|
||||||
There are a number of themes in Zero. Here are the important
|
|
||||||
ones:
|
|
||||||
|
|
||||||
### The Spring CLI
|
### The Spring 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.md](spring-cli/README.md).*
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
### Spring Bootstrap
|
### Spring Bootstrap
|
||||||
|
The main library providing features that support the other parts of Spring Zero.
|
||||||
|
Features include:
|
||||||
|
|
||||||
The main library providing features that support the other parts of
|
* `SpringApplication` - a class with static convenience methods that make it really easy
|
||||||
Spring Zero. Features include:
|
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-bootstrap/README.md](spring-bootstrap/README.md)._
|
||||||
|
|
||||||
* `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)
|
|
||||||
|
|
||||||
### Spring Autoconfigure
|
### 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.
|
||||||
|
|
||||||
Spring Zero can configure large parts of common applications based on
|
Auto-configuration attempts to guess what beans a user might want based on their
|
||||||
detecting the content of the classpath and any existing application
|
classpath. For example, If a 'HSQLDB' is on the classpath the user probably wants an
|
||||||
context:
|
in-memory database to be defined. Auto-configuration will back away as the user starts
|
||||||
|
to define their own beans.
|
||||||
|
|
||||||
|
_See [spring-autoconfigure/README.md](spring-autoconfigure/README.md)._
|
||||||
|
|
||||||
* `@EnableAutoConfigure` is an annotation that 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.
|
|
||||||
* `@Conditional` is an annotation in Spring 4.0 that allows you to
|
|
||||||
control which parts of an application are used at runtime. Spring
|
|
||||||
Zero provides some concrete implementations of conditional
|
|
||||||
configuration, e.g. `@ConditionalOnBean`,
|
|
||||||
`@ConditionalOnMissingBean` and `@ConditionalOnClass`.
|
|
||||||
|
|
||||||
### Spring Actuator
|
### 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
|
||||||
|
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.
|
||||||
|
|
||||||
Spring Actuator uses auto-configuration features to decorate
|
_See [spring-actuator/README.md](spring-actuator/README.md)._
|
||||||
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.
|
|
||||||
|
|
||||||
### Service Wrappers and Deployability
|
|
||||||
|
|
||||||
Spring Zero helps you to take that last step from finishing a
|
|
||||||
development iteration to getting the code running in production.
|
|
||||||
Without having to think too much about it, other than choosing your
|
|
||||||
deployment environment (CentOS, Ubuntu, Windows etc) you should be
|
|
||||||
able to stand up an instance, or multiple instances, of your component
|
|
||||||
and have them fit seamlessly into the operating system environment.
|
|
||||||
|
|
||||||
### Spring Starters
|
### 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.
|
||||||
|
|
||||||
Spring Starters are a set of convenient dependency
|
_See [spring-starters/README.md](spring-starters/README.md)._
|
||||||
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.
|
|
||||||
|
|
||||||
## Building the code
|
|
||||||
Use maven to build the source code.
|
|
||||||
|
|
||||||
$ mvn clean install
|
### 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`.
|
||||||
|
|
||||||
## Importing into eclipse
|
_See [spring-launcher/README.md](spring-launcher/README.md) &
|
||||||
You can use m2e or `maven eclipse:eclipse`.
|
[spring-package-maven-plugin/README.md](spring-package-maven-plugin/README.md)._
|
||||||
|
|
||||||
Project specific settings are configured for source formatting. If you
|
|
||||||
are using m2e you can follow these steps to install eclipse support
|
|
||||||
for formatting:
|
|
||||||
|
|
||||||
* Select `Install new software` from the `help` menu
|
|
||||||
* Click `Add...` to add a new repository
|
|
||||||
* Click the `Archive...` button
|
|
||||||
* Select `org.eclipse.m2e.maveneclipse.site-0.0.1-SNAPSHOT-site.zip`
|
|
||||||
from the `eclipse` folder in this checkout
|
|
||||||
* Install "Maven Integration for the maven-eclipse-plugin"
|
|
||||||
|
|
||||||
Or if you prefer you can import settings manually from the `/eclipse` folder.
|
|
||||||
|
|
||||||
## Samples
|
## Samples
|
||||||
The following samples are included. To run use `java -jar target/<archive>.jar`
|
Groovy samples for use with the command line application are available in
|
||||||
|
[spring-cli/samples](spring-cli/samples/). To run the CLI samples type
|
||||||
|
`spr run <sample>.groovy` from samples directory.
|
||||||
|
|
||||||
* spring-zero-simple-sample - A simple command line application
|
Java samples are available in [spring-zero-sample](spring-zero-samples/) and should
|
||||||
* spring-zero-jetty-sample - Embedded Jetty
|
be build with maven and run use `java -jar target/<sample>.jar`. The following java
|
||||||
* spring-zero-tomcat-sample - Embedded Tomcat
|
samples are provided:
|
||||||
* spring-zero-service-sample - Simple REST service with production features
|
|
||||||
* spring-batch-sample - Define and run a Batch job in a few lines of code
|
* spring-zero-sample-simple - A simple command line application
|
||||||
* spring-zero-data-sample - Spring Data JPA + Hibernate + HSQLDB
|
* spring-zero-sample-tomcat - Embedded Tomcat
|
||||||
|
* spring-zero-sample-jetty - Embedded Jetty
|
||||||
|
* spring-zero-sample-actuator - Simple REST service with production features
|
||||||
|
* spring-zero-sample-actuator-ui - A web UI example with production features
|
||||||
|
* spring-zero-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-zero-sample-integration - A spring integration application
|
||||||
|
* spring-zero-sample-profile - example showing Spring's `@profile` support
|
||||||
|
* spring-zero-sample-traditional - shows Spring Zero with more traditional WAR packaging
|
||||||
|
(but also executable using `java -jar`)
|
||||||
|
* spring-zero-sample-xml - Example show how Spring Zero can be mixed with trditional XML
|
||||||
|
configuration
|
||||||
|
|
||||||
|
1
spring-autoconfigure/README.md
Normal file
1
spring-autoconfigure/README.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# Spring AutoConfigure
|
1
spring-bootstrap/README.md
Normal file
1
spring-bootstrap/README.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# Spring Bootstrap
|
1
spring-cli/README.md
Normal file
1
spring-cli/README.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# Spring CLI
|
1
spring-launcher/README.md
Normal file
1
spring-launcher/README.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# Spring Launcher
|
1
spring-package-maven-plugin/README.md
Normal file
1
spring-package-maven-plugin/README.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# Spring Package Maven Plugin
|
1
spring-starters/README.md
Normal file
1
spring-starters/README.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# Spring Starters
|
Loading…
Reference in New Issue
Block a user