Spring/spring-boot
Spring/spring-boot
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-boot.git synced 2024-09-03 04:26:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

Documentation updates

Browse Source
This commit is contained in:
Phillip Webb 2013-08-09 15:34:04 -07:00
parent ce5e145afa
commit 878ff13620
8 changed files with 475 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
README.md
View File

@ -18,21 +18,20 @@ diverge from the defaults
* Absolutely no code generation and no requirement for XML configuration
## 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,
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.
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.
### Installing the CLI
> **Note:** If you don't want to use the CLI,
> [jump ahead to the Java example](#quick-start-java-example).
### Installing the CLI
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
(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:
$ java -version
@ -40,24 +39,20 @@ before you begin:
### Manual installation
You can download the Spring CLI distribution from the Spring software repository:
* [spring-boot-cli-0.5.0.M1-bin.zip](http://repo.springsource.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.M1-bin.tar.gz](http://repo.springsource.org/milestone/org/springframework/boot/spring-boot-cli/0.5.0.M1/spring-boot-cli-0.5.0.M1-bin.tar.gz)
* [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)
Cutting edge [snapshot distributions](http://repo.springsource.org/snapshot/org/springframework/boot/spring-boot-cli/)
Cutting edge [snapshot distributions](http://repo.springframework.org/snapshot/org/springframework/boot/spring-boot-cli/)
are also available.
Once downloaded, follow the
[INSTALL](spring-boot-cli/src/main/content/INSTALL.txt) instructions
from the unpacked archive. In summary: there is a `spring` script
(`spring.bat` for Windows) in a `bin/` directory in the `.zip` file,
or alternatively you can use `java -jar` with the `.jar` file (the
script helps you to be sure that the classpath is set correctly).
Once downloaded, follow the [INSTALL](spring-boot-cli/src/main/content/INSTALL.txt)
instructions from the unpacked archive.
### 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 http://repo.springsource.org/install/spring-boot-cli.rb
$ brew install spring-boot-cli
Homebrew will install `spring` to `/usr/local/bin`. Now you can jump right to a
[quick start example](#quick-start-script-example).
@ -312,9 +307,9 @@ A web UI example with production features
A thymeleaf web application
* [spring-boot-sample-web-static](spring-boot-samples/spring-boot-sample-web-static) -
A web application service static files
* [spring-boot-sample-batch](spring-boot-samples/spring-boot-sample-batch) -
* [spring-sample-batch](spring-boot-samples/spring-sample-batch) -
Define and run a Batch job in a few lines of code
* [spring-boot-sample-data-jpa](spring-boot-samples/spring-boot-sample-data-jpa) -
* [spring-sample-data-jpa](spring-boot-samples/spring-sample-data-jpa) -
Spring Data JPA + Hibernate + HSQLDB
* [spring-boot-sample-integration](spring-boot-samples/spring-boot-sample-integration) -
A spring integration application

3
spring-boot-samples/spring-boot-sample-tomcat/build.gradle
View File

@ -11,8 +11,7 @@ apply plugin: 'java'
apply plugin: 'spring-boot'
repositories {
mavenCentral()
maven { url "http://repo.springsource.org/libs-snapshot-local" }
mavenLocal()
}
dependencies {

10
spring-boot-tools/README.md Normal file
View File

@ -0,0 +1,10 @@
# Spring Boot - Tools
Spring Boot Tools provides a logical grouping for our various build system plugins, and
the modules that support them. We provide a
[spring-boot-maven-plugin](spring-boot-maven-plugin) and
[spring-boot-gradle-plugin](spring-boot-gradle-plugin) for Maven and Gradle respectively.
If you are interested in how we support executable archives, take a look at the
[spring-boot-loader](spring-boot-loader) module. If you need to create executable
archives from a different build system,
[spring-boot-loader-tools](spring-boot-loader-tools) may help.

71
spring-boot-tools/spring-boot-gradle-plugin/README.md
View File

@ -1,4 +1,71 @@
# Spring Boot - Gradle Plugin
The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, allowing you to
package executable jar or war archives.
> We are currently still working on documentation for Spring Boot. Please check back
> in the future.
## Including the plugin
To use the Spring Boot Gradle Plugin simply include a `buildscript` dependency and apply
the `spring-boot` plugin:
```groovy
buildscript {
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:{{project.version}}")
}
}
apply plugin: 'spring-boot'
```
If you are using a milestone or snapshot release you will also need to add appropriate
`repositories` reference:
```groovy
buildscript {
repositories {
maven.url "http://repo.springsource.org/snapshot"
manve.url "http://repo.springsource.org/milestone"
}
// ...
}
```
## Packaging executable jar and war files
Once the `spring-boot` plugin has been applied to your project it will automatically
attempt to rewrite archives to make them executable using the `repackage` task. You
should configure your project to build a jar or war (as appropriate) in the usual way.
The main class that you want to launch can either be specified using a configuration
option, or by adding a `Main-Class` attribute to the manifest. If you don't specify a
main class the plugin will search for a class with a
`public static void main(String[] args)` method.
To build and run a project artifact, you do something like this:
```
$ gradle build
$ java -jar build/libs/mymodule-0.0.1-SNAPSHOT.jar
```
### Repackage configuration
The gradle plugin automatically extends your build script DSL with a `springBoot` element
for configuration. Simply set the appropriate properties as you would any other gradle
extension:
```groovy
springBoot {
backupSource = false
}
```
The following configuration options are available:
| Name | Type | Description | Default Value |
|-----------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
| mainClass | String | The main class that should be run. If not specified the value from the manifest will be used, or if no manifest entry is the archive will be searched for a suitable class | |
| providedConfiguration | String | The name of the provided configuration | providedRuntime |
| backupSource | boolean | If the original source archive should be backed-up before being repackaged | true |
## Further Reading
For more information on how Spring Boot Loader archives work, take a look at the
[spring-boot-loader](../spring-boot-loader) module. If you prefer using Maven to
build your projects we have a [spring-boot-maven-plugin](../spring-boot-maven-plugin).

56
spring-boot-tools/spring-boot-loader-tools/README.md
View File

@ -1,4 +1,52 @@
# Spring Launcher
> We are currently still working on documentation for Spring Boot. Please check back
> in the future.
# Spring Boot - Loader Tools
The Spring Boot Loader Tools module provides support utilities to help when creating
[Spring Boot Loader](../spring-boot-loader) compatible archives. This module is
used by the various build system plugins that we provide.
> **Note:** The quickest way to build a compatible archive is to use the
> [spring-boot-maven-plugin](../spring-boot-maven-plugin) or
> [spring-boot-gradle-plugin](../spring-boot-gradle-plugin).
## Repackaging archives
To repackage an existing archive so that it becomes a self-contained executable archive
use `org.springframework.boot.loader.tools.Repackager`. The `Repackager` class takes a
single constructor argument that refers to an existing jar or war archive. Use one of the
two available `repackage()` methods to either replace the original file or write to a new
destination. Various settings can also be configured on the repackager before it is
run.
## Libraries
When repackaging an archive you can include references to dependency files using the
`org.springframework.boot.loader.tools.Libraries` interface. We don't provide any
concrete implementations of `Libraries` here as they are usually build system specific.
If your archive already includes libraries you can use `Libraries.NONE`
## Finding a main class
If you don't use `Repackager.setMainClass()` to specify a main class, the repackager will
use [ASM](http://asm.ow2.org/) to read class files and attempt to find a suitable class.
The first class with a `public static void main(String[] args)` method will be used.
Searching is performed using a breadth first algorithm, with the assumption that the main
class will appear high in the package structure.
## Example
Here is a typical example repackage:
```java
Repackager repackager = new Repackager(sourceJarFile);
repackager.setBackupSource(false);
repackager.repackage(new Libraries() {
@Override
public void doWithLibraries(LibraryCallback callback) throws IOException {
// Build system specific implementation, callback for each dependency
// callback.library(nestedFile, LibraryScope.COMPILE);
}
});
```
## Further Reading
For more information on how Spring Boot Loader archives work take a look at the
[spring-boot-loader](../spring-boot-loader) module. If you want to see how we use this
library the [Maven](../spring-boot-maven-plugin) and
[Gradle](../spring-boot-gradle-plugin) plugins are good place to start.

204
spring-boot-tools/spring-boot-loader/README.md
View File

@ -1,4 +1,202 @@
# Spring Boot - Loader
> We are currently still working on documentation for Spring Boot. Please check back
> in the future.
The Spring Boot Loader module allows JAR and WAR files that contain nested dependencies
to be run using `java -jar archive.jar`.
> **Note:** The quickest way to build a compatible archive is to use the
> [spring-boot-maven-plugin](../spring-boot-maven-plugin) or
> [spring-boot-gradle-plugin](../spring-boot-gradle-plugin).
## Nested JARs
Java does not provide any standard way to load nested jar files (i.e. jar files that
are themselves contained within a jar). This can be problematic if you are looking
to distribute a self contained application that you can just run from the command line
without unpacking.
To solve this problem, many developers use 'shaded' jars. A shaded jar simply packages
all classes, from all jars, into a single 'uber jar'. The problem with shaded jars is
that it becomes hard to see which libraries you are actually using in your application.
It can also be problematic if the the same filename is used (but with different content)
in multiple jars. Spring Boot takes a different approach and allows you to actually nest
jars directly.
### JAR file structure
Spring Boot Loader compatible jar files should be structured in the following way:
```
example.jar
|
+-META-INF
| +-MANIFEST.MF
+-org
| +-springframework
| +-boot
| +-loader
| +-<spring boot loader classes>
+-com
| +-mycompany
| + project
| +-YouClasses.class
+-lib
+-dependency1.jar
+-dependency2.jar
```
Dependencies should be placed in a nested `lib` directory.
See [executable-jar](src/it/executable-jar) for an example project.
### WAR file structure
Spring Boot Loader compatible war files should be structured in the following way:
```
example.jar
|
+-META-INF
| +-MANIFEST.MF
+-org
| +-springframework
| +-boot
| +-loader
| +-<spring boot loader classes>
+-WEB-INF
+-classes
| +-com
| +-mycompany
| +-project
| +-YouClasses.class
+-lib
| +-dependency1.jar
| +-dependency2.jar
+-lib-provided
+-servlet-api.jar
+-dependency3.jar
```
Dependencies should be placed in a nested `WEB-INF/lib` directory. Any dependencies
that are required when running embedded but are not required when deploying to
a traditional web container should be placed in `WEB-INF/lib-provided`.
See [executable-war](src/it/executable-war) for an example project.
## RandomAccessJarFile
The core class used to support loading nested jars is
`org.springframework.boot.loader.jar.RandomAccessJarFile`. It allows you load jar
content from a standard jar file or from nested child jar data. When first loaded, the
location of each `JarEntry` is mapped to a physical file offset of the outer jar:
```
myapp.jar
+---------+---------------------+
| | /lib/mylib.jar |
| A.class |+---------+---------+|
| || B.class | B.class ||
| |+---------+---------+|
+---------+---------------------+
^ ^ ^
0063 3452 3980
```
The example above shows how `A.class` can be found in `myapp.jar` position `0063`.
`B.class` from the nested jar can actually be found in `myapp.jar` position `3452`
and `B.class` is at position `3980`.
Armed with this information, we can load specific nested entries by simply seeking to
appropriate part if the outer jar. We don't need to unpack the archive and we don't
need to read all entry data into memory.
### Compatibility
Spring Boot Loader strives to remain compatible with existing code and libraries. The
`RandomAccessJarFile` extends from `java.util.jar.JarFile` and should work as a drop-in
replacement. The `RandomAccessJarFile.getURL()` method will return a `URL` that opens
a `java.net.JarURLConnection` compatible connection. `RandomAccessJarFile` URLs can
be used with Java's `URLClassLoader`.
## Launching
The `org.springframework.boot.loader.Launcher` class can be used to run your packaged
application. It takes care of setting up an appropriate `URLClassLoader` and calling
your `main()` method.
### Launcher manifest
You need specify an appropriate `Launcher` as the `Main-Class` attribute of
`META-INF/MANIFEST.MF`. The actual class that you want to launch (i.e. the class that
you wrote that contains a `main` method) should be specified in the `Start-Class`
attribute.
For example, here is a typical `MANIFEST.MF` for a executable jar file:
```
Main-Class: org.springframework.boot.loader.JarLauncher
Start-Class: com.mycompany.project.MyApplication
```
For a war file, it would be:
```
Main-Class: org.springframework.boot.loader.WarLauncher
Start-Class: com.mycompany.project.MyApplication
```
> **Note:** You do not need to specify `Class-Path` entries in your manifest file, the
> classpath will be deduced from the nested jars.
### Exploded archives
Certain PaaS implementations may choose to unpack archives before they run. For example,
Cloud Foundry operates in this way. You can run an unpacked archive by simply starting
the appropriate launcher:
```
$ unzip -q myapp.jar
$ java org.springframework.boot.loader.JarLauncher
```
## Restrictions
There are a number of restrictions that you need to consider when working with a Spring
Boot Loader packaged application.
### URLs
URLs for nested jar entries intentionally look and behave like standard jar URLs,
You cannot, however, directly create a nested jar URL from a string:
```
URL url = classLoader.getResoure("/a/b.txt");
String s = url.toString(); // In the form 'jar:file:/file.jar!/nested.jar!/a/b.txt'
new URL(s); // This will fail
```
If you need to obtain URL using a String, ensure that you always provide a context URL
to the constructor. This will ensure that the custom `URLStreamHandler` used to support
nested jars is used.
```
URL url = classLoader.getResoure("/a");
new URL(url, "b.txt");
```
### Zip entry compression
The `ZipEntry` for a nested jar must be saved using the `ZipEntry.STORED` method. This
is required so that we can seek directly to individual content within the nested jar.
The content of the nested jar file itself can still be compressed, as can any other
entries in the outer jar. You can use the Spring Boot
[Maven](../spring-boot-maven-plugin) or [Gradle](../spring-boot-gradle-plugin) plugins
to ensure that your archives are written correctly.
### System ClassLoader
Launched applications should use `Thread.getContextClassLoader()` when loading classes
(most libraries and frameworks will do this by default). Trying to load nested jar
classes via `ClassLoader.getSystemClassLoader()` will fail. Please be aware that
`java.util.Logging` always uses the system classloader, for this reason you should
consider a different logging implementation.
### Alternatives
If the above restrictions mean that you cannot use Spring Boot Loader the following
alternatives could be considered:
* [Maven Shade Plugin](http://maven.apache.org/plugins/maven-shade-plugin/)
* [JarClassLoader](http://www.jdotsoft.com/JarClassLoader.php)
* [OneJar](http://one-jar.sourceforge.net)
## Further Reading
For more information about any of the classes or interfaces discussed in the document
please refer to the project Javadoc. If you need to build a compatible archives see the
[spring-boot-maven-plugin](../spring-boot-maven-plugin) or
[spring-boot-gradle-plugin](../spring-boot-gradle-plugin). If you are not using Maven
or Gradle [spring-boot-loader-tools](../spring-boot-loader-tools) provides some useful
utilities to rewite existing zip files.

157
spring-boot-tools/spring-boot-maven-plugin/README.md
View File

@ -1,41 +1,138 @@
# Spring Boot - Maven Plugin
The Spring Boot Maven Plugin provides Spring Boot support in Maven, allowing you to
package executable jar or war archives and run an application in-place.
> **Note:** We are currently still working on documentation for Spring Boot. This
> README is not yet complete, please check back in the future.
A maven plugin for building executable JAR and WAR files. To use it,
configure your project to build a JAR or WAR (as appropriate) in the
normal way, and then add the Spring plugin to your `<build><plugins>`
section
`pom.xml`
## Including the plugin
To use the Spring Boot Maven Plugin simply include the appropriate XML in the `plugins`
section of your `pom.xml`
```xml
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-package-maven-plugin</artifactId>
<version>{{project.version}}</version>
<executions>
<execution>
<goals>
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>
<?xml version="1.0" encoding="UTF-8"?>
<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>
<!-- ... -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-package-maven-plugin</artifactId>
<version>{{project.version}}</version>
<executions>
<execution>
<goals>
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
```
The net effect of that is to enhance your existing archive with the
Spring Launcher during the Maven `package` phase. The main class will
be selected from the existing `MANIFEST.MF` if there is one, or else
the plugin will attempt to guess based on the contents of the local
`src/main/java` source tree.
If you are using a milestone or snapshot release you will also need to add appropriate
`pluginRepository` elements:
So to build and run a project artifact you do something like this:
```xml
<pluginRepositories>
<pluginRepository>
<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>
```
## Packaging executable jar and war files
Once `spring-package-maven-plugin` has been included in your `pom.xml` it will
automatically attempt to rewrite archives to make them executable using the
`spring-boot:repackage` goal. You should configure your project to build a jar or war
(as appropriate) using the usual `packaging` element:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<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">
<!-- ... -->
<packaging>jar</packaging>
<!-- ... -->
</project>
```
Your existing archive will be enhanced by Spring Boot during the `package`
phase. The main class that you want to launch can either be specified using a
configuration option, or by adding a `Main-Class` attribute to the manifest in the usual
way. If you don't specify a main class the plugin will search for a class with a
`public static void main(String[] args)` method.
To build and run a project artifact, you do something like this:
```
$ mvn package
$ java -jar target/*.jar
...
<application runs>
$ java -jar target/mymodule-0.0.1-SNAPSHOT.jar
```
### Repackage configuration
The following configuration options are available for the `spring-boot:repackage` goal:
**Required Parameters**
| Name | Type | Description | Default Value |
|-----------------|--------|--------------------------------------------|----------------------------|
| outputDirectory | File | Directory containing the generated archive | ${project.build.directory} |
| finalName | String | Name of the generated archive | ${project.build.finalName} |
**Optional Parameters**
| Name | Type | Description |
|-----------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| classifier | String | Classifier to add to the artifact generated. If given, the artifact will be attached. If this is not given, it will merely be written to the output directory according to the finalName |
| mainClass | String | The name of the main class. If not specified the first compiled class found that contains a 'main' method will be used |
## Running applications
The Spring Boot Maven Plugin includes a `run` goal which can be used to launch your
application from the command line. Type the following from the root of your maven
project:
```
$ mvn spring-boot:run
```
By default, any `src/main/resources` folder will be added to the application classpath
when you run via the maven plugin. This allows hot refreshing of resources which can be
very useful when web applications. For example, you can work on HTML, CSS or JavaScipt
files and see your changes immediately without recompiling your application. It is also
a helpful way of allowing your front end developers to work without needing to download
and install a Java IDE.
### Run configuration
The following configuration options are available for the `spring-boot:run` goal:
**Required Parameters**
| Name | Type | Description | Default Value |
|--------------------------------------|---------|----------------------------------------------------------------------------------------------|----------------------------------|
| classesDirectrory | File | Directory containing the classes and resource files that should be packaged into the archive | ${project.build.outputDirectory} |
**Optional Parameters**
| Name | Type | Description | Default Value |
|--------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|
| arguments (or -Drun.arguments) | String[] | Arguments that should be passed to the application | |
| addResources (or -Drun.addResources) | boolean | Add maven resources to the classpath directly, this allows live in-place editing or resources. Since resources will be added directly, and via the target/classes folder they will appear twice if ClassLoader.getResources() is called. In practice however most applications call ClassLoader.getResource() which will always return the first resource | true |
| mainClass | String | The name of the main class. If not specified the first compiled class found that contains a 'main' method will be used | |
| folders | String[] | Folders that should be added to the classpath | ${project.build.outputDirectory} |
## Further Reading
For more information on how Spring Boot Loader archives work, take a look at the
[spring-boot-loader](../spring-boot-loader) module. If you prefer using Gradle to
build your projects we have a [spring-boot-gradle-plugin](../spring-boot-gradle-plugin).

4
spring-boot/README.md
View File

@ -138,8 +138,8 @@ refer to an explicit location using the `spring.config.location` environment pro
$ java -jar myproject.jar --spring.config.name=myproject
_NOTE: You can also use '.yaml' files as an alternative to '.properties' (see
[below](#using-yaml-instead-of-properties))_
> **Note:** You can also use '.yaml' files as an alternative to '.properties' (see
> [below](#using-yaml-instead-of-properties))_
### Setting the Default Spring Profile
Spring Profiles are a way to segregate parts of the application configuration and make it