Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add maven plugin documentation

Browse Source 
This commit adds the generated site for the maven plugin alongside
the developer guide and javadoc. The maven plugin is available in
the "/maven-plugin" context.

The advanced information described in the developer guide have
been migrated to the plugin site as most the information is taken
from the code itself, which avoids duplication.

Fixes #749
This commit is contained in:
Stephane Nicoll
2014-05-02 17:51:23 +02:00
committed by Dave Syer
parent a3b422ffc8
commit 888703cf26
12 changed files with 385 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
spring-boot-tools/spring-boot-maven-plugin/src/assemble/site.xml Normal file
View File

@@ -0,0 +1,15 @@
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
<id>site</id>
<baseDirectory>maven-plugin</baseDirectory>
<formats>
<format>zip</format>
</formats>
<fileSets>
<fileSet>
<directory>${project.build.directory}/site</directory>
<outputDirectory>/</outputDirectory>
</fileSet>
</fileSets>
</assembly>

28
spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RepackageMojo.java
View File

@@ -37,39 +37,46 @@ import org.springframework.boot.loader.tools.Libraries;
import org.springframework.boot.loader.tools.Repackager;
/**
* MOJO that can can be used to repackage existing JAR and WAR archives so that they can
* be executed from the command line using {@literal java -jar}. With
* <code>layout=NONE</code> can also be used simply to package a JAR with nested
* dependencies (and no main class, so not executable).
* Repackages existing JAR and WAR archives so that they can be executed from
* the command line using {@literal java -jar}. With <code>layout=NONE</code>
* can also be used simply to package a JAR with nested dependencies (and
* no main class, so not executable).
*
* @author Phillip Webb
* @author Dave Syer
* @author Stephane Nicoll
*/
@Mojo(name = "repackage", defaultPhase = LifecyclePhase.PACKAGE, requiresProject = true, threadSafe = true, requiresDependencyResolution = ResolutionScope.COMPILE_PLUS_RUNTIME, requiresDependencyCollection = ResolutionScope.COMPILE_PLUS_RUNTIME)
@Mojo(name = "repackage", defaultPhase = LifecyclePhase.PACKAGE, requiresProject = true,
threadSafe = true, requiresDependencyResolution = ResolutionScope.COMPILE_PLUS_RUNTIME,
requiresDependencyCollection = ResolutionScope.COMPILE_PLUS_RUNTIME)
public class RepackageMojo extends AbstractMojo {
private static final long FIND_WARNING_TIMEOUT = TimeUnit.SECONDS.toMillis(10);
/**
* The Maven project.
* @since 1.0
*/
@Parameter(defaultValue = "${project}", readonly = true, required = true)
private MavenProject project;
/**
* Maven project helper utils.
* @since 1.0
*/
@Component
private MavenProjectHelper projectHelper;
/**
* Directory containing the generated archive.
* @since 1.0
*/
@Parameter(defaultValue = "${project.build.directory}", required = true)
private File outputDirectory;
/**
* Name of the generated archive.
* @since 1.0
*/
@Parameter(defaultValue = "${project.build.finalName}", required = true)
private String finalName;
@@ -77,7 +84,10 @@ public class RepackageMojo extends AbstractMojo {
/**
* 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.
* according to the finalName. Attaching the artifact allows to deploy it alongside
* to the original one, see <a href="http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploying-with-classifiers.html">
* the maven documentation for more details</a>.
* @since 1.0
*/
@Parameter
private String classifier;
@@ -85,12 +95,16 @@ public class RepackageMojo extends AbstractMojo {
/**
* The name of the main class. If not specified the first compiled class found that
* contains a 'main' method will be used.
* @since 1.0
*/
@Parameter
private String mainClass;
/**
* The layout to use (JAR, WAR, ZIP, DIR, NONE) in case it cannot be inferred.
* The type of archive (which corresponds to how the dependencies are laid out
* inside it). Possible values are JAR, WAR, ZIP, DIR, NONE. Defaults to a
* guess based on the archive type.
* @since 1.0
*/
@Parameter
private LayoutType layout;

22
spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RunMojo.java
View File

@@ -43,11 +43,13 @@ import org.springframework.boot.loader.tools.RunProcess;
import edu.emory.mathcs.backport.java.util.Arrays;
/**
* MOJO that can be used to run a executable archive application directly from Maven.
* Run an executable archive application.
*
* @author Phillip Webb
* @author Stephane Nicoll
*/
@Mojo(name = "run", requiresProject = true, defaultPhase = LifecyclePhase.VALIDATE, requiresDependencyResolution = ResolutionScope.TEST)
@Mojo(name = "run", requiresProject = true, defaultPhase = LifecyclePhase.VALIDATE,
requiresDependencyResolution = ResolutionScope.TEST)
@Execute(phase = LifecyclePhase.TEST_COMPILE)
public class RunMojo extends AbstractMojo {
@@ -55,25 +57,32 @@ public class RunMojo extends AbstractMojo {
/**
* The Maven project.
* @since 1.0
*/
@Parameter(defaultValue = "${project}", readonly = true, required = true)
private MavenProject project;
/**
* Add maven resources to the classpath directly, this allows live in-place editing or
* resources.
* resources. Since resources will be added directly, and via the target/classes folder
* they will appear twice if {@code ClassLoader.getResources()} is called. In practice,
* however, most applications call {@code ClassLoader.getResource()} which will always
* return the first resource.
* @since 1.0
*/
@Parameter(property = "run.addResources", defaultValue = "true")
private boolean addResources;
/**
* Path to agent jar.
* @since 1.0
*/
@Parameter(property = "run.agent")
private File[] agent;
/**
* Flag to say that the agent requires -noverify.
* @since 1.0
*/
@Parameter(property = "run.noverify")
private Boolean noverify;
@@ -81,6 +90,7 @@ public class RunMojo extends AbstractMojo {
/**
* Arguments that should be passed to the application. On command line use commas to
* separate multiple arguments.
* @since 1.0
*/
@Parameter(property = "run.arguments")
private String[] arguments;
@@ -88,12 +98,15 @@ public class RunMojo extends AbstractMojo {
/**
* The name of the main class. If not specified the first compiled class found that
* contains a 'main' method will be used.
* @since 1.0
*/
@Parameter
private String mainClass;
/**
* Folders that should be added to the classpath.
* Additional folders besides the classes directory that should be added to
* the classpath.
* @since 1.0
*/
@Parameter
private String[] folders;
@@ -101,6 +114,7 @@ public class RunMojo extends AbstractMojo {
/**
* Directory containing the classes and resource files that should be packaged into
* the archive.
* @since 1.0
*/
@Parameter(defaultValue = "${project.build.outputDirectory}", required = true)
private File classesDirectory;

49
spring-boot-tools/spring-boot-maven-plugin/src/site/apt/examples/repackage-classifier.apt Normal file
View File

@@ -0,0 +1,49 @@
-----
Repackage classifier
-----
Stephane Nicoll
-----
2014-05-02
-----
By default, the <<<repackage>>> goal will replace the original artifact with the
executable one. If you prefer to keep the original artifact and attach the executable
one with a different classifier, configure the plugin as follows:
---
<project>
...
<build>
...
<plugins>
...
<plugin>
<groupId>${project.groupId}</groupId>
<artifactId>${project.artifactId}</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
<configuration>
<classifier>exec</classifier>
</configuration>
</execution>
</executions>
...
</plugin>
...
</plugins>
...
</build>
...
</project>
---
This configuration will generate two artifacts: the original one and the executable counter
part produced by the repackage goal. Both will be installed/deployed accordingly.

44
spring-boot-tools/spring-boot-maven-plugin/src/site/apt/index.apt Normal file
View File

@@ -0,0 +1,44 @@
-----
Spring Boot
-----
Stephane Nicoll
-----
2014-05-02
-----
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”.
* Goals Overview
The Spring Boot Plugin has the following goals.
* {{{./run-mojo.html}spring-boot:run}} runs your Spring Boot application.
* {{{./repackage-mojo.html}spring-boot:repackage}} repackages your jar/war to be executable.
* Usage
General instructions on how to use the Spring Boot Plugin can be found on the {{{./usage.html}usage page}}. Some
more specific use cases are described in the examples given below.
In case you still have questions regarding the plugin's usage, please have a look at the existing
{{{http://stackoverflow.com/questions/tagged/spring-boot}stack overflow issue}}. If you still don't get an
answer, feel free to create a new thread with the <<<#spring-boot>>> tag.
If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report
in our {{{./issue-tracking.html}issue tracker}}.
* Examples
To provide you with better understanding of some usages of Spring Boot, you can take a look into
the following examples:
* {{{./examples/repackage-classifier.html}Custom repackage classifier}}
[]

123
spring-boot-tools/spring-boot-maven-plugin/src/site/apt/usage.apt.vm Normal file
View File

@@ -0,0 +1,123 @@
-----
Usage
-----
Stephane Nicoll
-----
2014-05-02
-----
Usage
The plugin offers a goal for repackaging an application as an executable JAR/WAR as well as a goal
for running the application.
* Repackaging an application
In order to repackage your application, you simply need to add a reference to the
plugin in your <<<pom.xml>>>:
---
<build>
...
<plugins>
...
<plugin>
<groupId>${project.groupId}</groupId>
<artifactId>${project.artifactId}</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
...
</build>
---
The example above repackages a jar or war that is built during the package phase of the Maven lifecycle. The
original (i.e. non exectuable) artifact is renamed to <<<.original>>> by default but it is also possible to
keep the original artifact using a custom classifier.
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.
---
<build>
...
<plugins>
...
<plugin>
<groupId>${project.groupId}</groupId>
<artifactId>${project.artifactId}</artifactId>
<version>${project.version}</version>
<configuration>
<mainClass>${start-class}</mainClass>
<layout>ZIP</layout>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
...
</build>
---
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).
For more detailed examples of how to configure this goal see:
* {{{./examples/repackage-classifier.html}Custom repackage classifier}}
[]
* Running the application
The plugin includes a run goal which can be used to launch your application from the command
line:
---
mvn spring-boot:run
---
By default, any <<src/main/resources>> folder will be added to the application classpath
when you run the application. This allows hot refreshing of resources which can be very
useful when developing 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.
Of course, if your resources are using tokens that are filtered by Maven, you may want
to disable that feature as follows:
---
<build>
...
<plugins>
...
<plugin>
<groupId>${project.groupId}</groupId>
<artifactId>${project.artifactId}</artifactId>
<version>${project.version}</version>
<configuration>
<addResources>false</mainClass>
</configuration>
</plugin>
...
</plugins>
...
</build>
---

19
spring-boot-tools/spring-boot-maven-plugin/src/site/site.xml Normal file
View File

@@ -0,0 +1,19 @@
<project xmlns="http://maven.apache.org/DECORATION/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
<body>
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<item name="Goals" href="plugin-info.html"/>
<item name="Usage" href="usage.html"/>
</menu>
<menu name="Examples">
<item name="Custom repackage classifier" href="examples/repackage-classifier.html"/>
</menu>
<menu ref="reports"/>
</body>
<skin>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-fluido-skin</artifactId>
<version>1.3.1</version>
</skin>
</project>