Remove duplicate documentation
Remove README files that have been since been migrated to the reference documentation. Also updated remaining markdown files to asciidoctor to save having a mix of different formats. Fixed gh-503
This commit is contained in:
@@ -1,10 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,4 +0,0 @@
|
||||
# Spring Boot - Dependency Tools
|
||||
The Spring Boot Dependency Tools module provides support utilities to help when resolving
|
||||
'blessed' Spring Boot dependencies. It basically provides programmatic access to the
|
||||
managed dependencies section of `spring-boot-dependencies/pom.xml`
|
||||
@@ -1,192 +0,0 @@
|
||||
# Spring Boot - Gradle Plugin
|
||||
The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, allowing you to
|
||||
package executable jar or war archives, run Spring Boot applications and remove version
|
||||
information from your `build.gradle` file.
|
||||
|
||||
## 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.spring.io/snapshot"
|
||||
maven.url "http://repo.spring.io/milestone"
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## Declaring dependencies without versions
|
||||
The `spring-boot` plugin will register a custom Gradle `ResolutionStrategy` with your
|
||||
build that allows you to omit version numbers when declaring dependencies to known
|
||||
artifacts. All artifacts with a `org.springframework.boot` group ID, and any of the
|
||||
artifacts declared in the `managementDependencies` section of the `spring-dependencies`
|
||||
POM can have their version number resolved automatically.
|
||||
|
||||
Simply declare dependencies in the usual way, but leave the version number empty:
|
||||
|
||||
```groovy
|
||||
dependencies {
|
||||
compile("org.springframework.boot:spring-boot-starter-web")
|
||||
compile("org.thymeleaf:thymeleaf-spring4")
|
||||
compile("nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect")
|
||||
}
|
||||
```
|
||||
|
||||
## 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 `bootRepackage` 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
|
||||
```
|
||||
|
||||
### Running a Project in Place
|
||||
To run a project in place without building a jar first you can use the "bootRun" task:
|
||||
|
||||
```
|
||||
$ gradle bootRun
|
||||
```
|
||||
|
||||
Running this way makes your static classpath resources (i.e. in
|
||||
`src/main/resources` by default) reloadable in the live application,
|
||||
which can be helpful at development time.
|
||||
|
||||
### 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
|
||||
}
|
||||
```
|
||||
|
||||
### Repackage with Custom Gradle Configuration
|
||||
Sometimes it may be more appropriate to not package default dependencies resolved from
|
||||
`compile`, `runtime` and `provided` scopes. If created executable jar file
|
||||
is intended to be run as it is you need to have all dependencies in it, however
|
||||
if a plan is to explode a jar file and run main class manually you may already
|
||||
have some of the libraries available via `CLASSPATH`. This is a situation where
|
||||
you can repackage boot jar with a different set of dependencies. Using a custom
|
||||
configuration will automatically disable dependency resolving from
|
||||
`compile`, `runtime` and `provided` scopes. Custom configuration can be either
|
||||
defined globally inside `springBoot` or per task.
|
||||
|
||||
```groovy
|
||||
task clientJar(type: Jar) {
|
||||
appendix = 'client'
|
||||
from sourceSets.main.output
|
||||
exclude('**/*Something*')
|
||||
}
|
||||
|
||||
task clientBoot(type: BootRepackage, dependsOn: clientJar) {
|
||||
withJarTask = clientJar
|
||||
customConfiguration = "mycustomconfiguration"
|
||||
}
|
||||
```
|
||||
In above example we created a new `clientJar` Jar task to package a customized
|
||||
file set from your compiled sources. Then we created a new `clientBoot`
|
||||
BootRepackage task and instructed it to work with only `clientJar` task and
|
||||
`mycustomconfiguration`.
|
||||
|
||||
```groovy
|
||||
configurations {
|
||||
mycustomconfiguration.exclude group: 'log4j'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
mycustomconfiguration configurations.runtime
|
||||
}
|
||||
```
|
||||
Configuration we are referring to in `BootRepackage` is a normal
|
||||
Gradle configuration. In above example we created a new configuration
|
||||
named `mycustomconfiguration` instructing it to derive from a `runtime`
|
||||
and exclude `log4j` group. If `clientBoot` task is executed, repackaged
|
||||
boot jar will have all dependencies from a runtime but no
|
||||
log4j jars.
|
||||
|
||||
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 |
|
||||
| customConfiguration | String | The name of the custom configuration | none |
|
||||
| layout | String | The type of archive (which corresponds to how the dependencies are layed out inside it). Defaults to a guess based on the archive type. |
|
||||
|
||||
## Further Reading
|
||||
For more information on how Spring Boot Loader archives work, take a look at the
|
||||
[spring-boot-loader](../spring-boot-loader/README.md) module. If you prefer using Maven to
|
||||
build your projects we have a [spring-boot-maven-plugin](../spring-boot-maven-plugin/README.md).
|
||||
|
||||
### Understanding how Boot Gradle Plugin Works
|
||||
When `spring-boot` is applied to your Gradle project a default task
|
||||
named `bootRepackage` is created automatically. Boot repackage task
|
||||
depends on Gradle `assemble` task and when executed, it tries to find
|
||||
all jar artifacts whose qualifier is empty(meaning i.e. tests and
|
||||
sources jars are automatically skipped).
|
||||
|
||||
Because on default every repackage task execution will find all
|
||||
created jar artifacts, the order of Gradle task execution is
|
||||
important. This is not going to be an issue if you have a normal
|
||||
project setup where only one jar file is created. However if you are
|
||||
planning to create more complex project setup with custom Jar and
|
||||
BootRepackage tasks, there are few tweaks to consider.
|
||||
|
||||
```groovy
|
||||
jar.enabled = false
|
||||
bootRepackage.enabled = false
|
||||
```
|
||||
Above example simply disables default `jar` and `bootRepackage` tasks.
|
||||
This would be all right if you are just creating custom jar files
|
||||
out from your project. You could also just disable default
|
||||
`bootRepackage` task.
|
||||
|
||||
```groovy
|
||||
bootRepackage.withJarTask = jar
|
||||
```
|
||||
Above example simply instructs default `bootRepackage` task to only
|
||||
work with a default `jar` task.
|
||||
|
||||
|
||||
```groovy
|
||||
task bootJars
|
||||
bootJars.dependsOn = [clientBoot1,clientBoot2,clientBoot3]
|
||||
build.dependsOn(bootJars)
|
||||
```
|
||||
If you still have a default project setup where main jar file is
|
||||
created and repackaged to be used with boot and you still want to
|
||||
create additional custom jar files out from your project, you
|
||||
could simple combine you custom repackage tasks together and
|
||||
create dependency to your build so that `bootJars` task would
|
||||
be run after the default `bootRepackage` task is executed.
|
||||
|
||||
All the above tweaks are usually used to avoid situation where
|
||||
already created boot jar is repackaged again. Repackaging
|
||||
an existing boot jar will not break anything but you may
|
||||
get unnecessary dependencies in it.
|
||||
@@ -1,52 +0,0 @@
|
||||
# Spring Boot - Loader Tools
|
||||
The Spring Boot Loader Tools module provides support utilities to help when creating
|
||||
[Spring Boot Loader](../spring-boot-loader/README.md) 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/README.md) or
|
||||
> [spring-boot-gradle-plugin](../spring-boot-gradle-plugin/README.md).
|
||||
|
||||
## 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/README.md) module. If you want to see how we use this
|
||||
library the [Maven](../spring-boot-maven-plugin/README.md) and
|
||||
[Gradle](../spring-boot-gradle-plugin/README.md) plugins are good place to start.
|
||||
@@ -1,228 +0,0 @@
|
||||
# Spring Boot - Loader
|
||||
|
||||
The Spring Boot Loader module allows JAR and WAR files that contain
|
||||
nested dependencies to be run using `java -jar archive.jar`. There are
|
||||
3 launcher classes (`JarLauncher`, `WarLauncher` and
|
||||
`PropertiesLauncher`). Their purpose is to load resources (.class
|
||||
files etc.) from nested JAR files or JAR files in directories (as
|
||||
opposed to explicitly on the classpath). In the case of the
|
||||
`[Jar|War]Launcher` the nested paths are fixed `(lib/*.jar` and
|
||||
`lib-provided/*.jar` for the WAR case) so you just add extra JARs in
|
||||
those locations if you want more. The `PropertiesLauncher` looks in
|
||||
`lib/` by default, but you can add additional locations by setting an
|
||||
environment variable `LOADER_PATH`or `loader.path` in
|
||||
`application.properties` (colon-separated list of directories or archives).
|
||||
|
||||
> **Note:** The quickest way to build a compatible archive is to use the
|
||||
> [spring-boot-maven-plugin](../spring-boot-maven-plugin/README.md) or
|
||||
> [spring-boot-gradle-plugin](../spring-boot-gradle-plugin/README.md).
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## PropertiesLauncher Features
|
||||
|
||||
`PropertiesLauncher` has a few special features that can be enabled
|
||||
with external properties (System properties, environment variables,
|
||||
manifest entries or `application.properties`).
|
||||
|
||||
| Key | Purpose | Typical value |
|
||||
|------------|---------|---------------|
|
||||
|loader.path |Classpath (colon-separated) |lib:${HOME}/app/lib|
|
||||
|loader.home |Location of additional properties file (defaults to `${user.dir}`) |file:///opt/app|
|
||||
|loader.args |Default arguments for the main method (space separated) ||
|
||||
|loader.main |Name of main class to launch | com.app.Application |
|
||||
|loader.config.name|Name of properties file (default "application") | loader|
|
||||
|loader.config.location|Path to properties file (default "application/.properties") | classpath:loader.properties|
|
||||
|loader.system|Boolean flag to indicate that all properties should be added to System properties (default false)|true|
|
||||
|
||||
Manifest entry keys are formed by capitalizing intial letters of words
|
||||
and changing the separator to '-' from '.' (e.g. "Loader-Path"). The
|
||||
exception is "loader.main" which is looked up as "Start-Class" in the
|
||||
manifest for compatibility with `JarLauncher`).
|
||||
|
||||
Environment variables can be capitalized with underscore separators
|
||||
instead of periods.
|
||||
|
||||
* `loader.home` is the directory location of an additional properties
|
||||
file (overriding the default) as long as `loader.config.location` is
|
||||
not specified
|
||||
* `loader.path` can contain directories (scanned recursively for jar
|
||||
and zip files), archive paths, or wildcard patterns (for the default
|
||||
JVM behaviour)
|
||||
* Placeholder replacement is done from System and environment
|
||||
variables plus the properties file itself on all values before use.
|
||||
|
||||
## Restrictions
|
||||
There are a number of restrictions that you need to consider when working with a Spring
|
||||
Boot Loader packaged application.
|
||||
|
||||
### 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/README.md) or
|
||||
[Gradle](../spring-boot-gradle-plugin/README.md) 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/README.md) or
|
||||
[spring-boot-gradle-plugin](../spring-boot-gradle-plugin/README.md). If you are not using
|
||||
Maven or Gradle [spring-boot-loader-tools](../spring-boot-loader-tools/README.md) provides
|
||||
some useful utilities to rewite existing zip files.
|
||||
@@ -1,185 +0,0 @@
|
||||
# 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. To use it you must be using Maven 3 (or better).
|
||||
|
||||
## Including the plugin
|
||||
To use the Spring Boot Maven Plugin simply include the appropriate XML in the `plugins`
|
||||
section of your `pom.xml`
|
||||
|
||||
```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">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<!-- ... -->
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<version>{{project.version}}</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>repackage</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
```
|
||||
|
||||
This configuration will repackage a JAR or WAR that is built in the
|
||||
"package" phase of the Maven lifecycle, so
|
||||
|
||||
```
|
||||
$ mvn package
|
||||
$ ls target/*.jar
|
||||
target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original
|
||||
```
|
||||
|
||||
will reveal the result. If you don't include the `<execution/>`
|
||||
configuration as above you can run the plugin on its own, but only if
|
||||
the package goal is used as well, e.g.
|
||||
|
||||
```
|
||||
$ mvn package spring-boot:repackage
|
||||
```
|
||||
|
||||
will have the same effect as above.
|
||||
|
||||
If you are using a milestone or snapshot release you will also need to add appropriate
|
||||
`pluginRepository` elements:
|
||||
|
||||
```xml
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>spring-snapshots</id>
|
||||
<url>http://repo.spring.io/snapshot</url>
|
||||
</pluginRepository>
|
||||
<pluginRepository>
|
||||
<id>spring-milestones</id>
|
||||
<url>http://repo.spring.io/milestone</url>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
```
|
||||
|
||||
## Packaging executable jar and war files
|
||||
Once `spring-boot-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/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 |
|
||||
| layout | String | The type of archive (which corresponds to how the dependencies are layed out inside it). Defaults to a guess based on the archive type. |
|
||||
|
||||
The plugin rewrites your manifest, and in particular it manages the
|
||||
`Main-Class` and `Start-Class` entries, so if the defaults don't work
|
||||
you have to configure those there (not in the jar plugin). The
|
||||
`Main-Class` in the manifest is actually controlled by the `layout`
|
||||
property of the boot plugin, e.g.
|
||||
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<version>{{project.version}}</version>
|
||||
<configuration>
|
||||
<mainClass>${start-class}</mainClass>
|
||||
<layout>ZIP</layout>
|
||||
</configuration>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>repackage</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
|
||||
The layout property defaults to a guess based on the archive type (JAR
|
||||
or WAR). For the `PropertiesLauncher` the layout is "ZIP" (even though
|
||||
the output might be a JAR file).
|
||||
|
||||
## 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/README.md) module. If you prefer using Gradle to
|
||||
build your projects we have a [spring-boot-gradle-plugin](../spring-boot-gradle-plugin/README.md).
|
||||
Reference in New Issue
Block a user