
 -----
 Usage
 -----
 Stephane Nicoll
 -----
 2014-05-06
 -----

Usage

  The plugin provides several goals to work with a Spring Boot application:

  * <<<repackage>>>: create a jar or war file that is auto-executable. It can replace the regular artifact or can be
    attached to the build lifecycle with a separate <<classifier>>.

  * <<<run>>>: run your Spring Boot application with several options to pass parameters to it.

  * <<<start>>> and <<<stop>>>: integrate your Spring Boot application to the <<<integration-test>>> phase so that
   the application starts before it.

  * <<<build-info>>>: generate a build information that can be used by the Actuator.

   []

  Each goal is further described below.

* 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,
  including any <<<provided>>> dependencies that are defined in the project. If some of these dependencies
  need to be excluded, you can use one of the exclude options,
  see {{{./examples/exclude-dependency.html}Exclude a dependency}} for more details.
  Please note that the <<<outputFileNameMapping>>> feature of the <<<maven-war-plugin>>>
  is currently not supported.

  Devtools is automatically excluded by default (you can control that using the
  <<<excludeDevtools>>> property). In order to make that work with <<<war>>> packaging,
  the `spring-boot-devtools` dependency must be set as <<<optional>>> or with the
  <<<provided>>> scope.

  The original (i.e. non executable) 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>>>). The
  following layouts are available:

    * <<<JAR>>>: regular executable JAR layout.

    * <<<WAR>>>: executable WAR layout. <<<provided>>> dependencies are placed in <<<WEB-INF/lib-provided>>>
      to avoid any clash when the <<<war>>> is deployed in a servlet container.

    * <<<ZIP>>> (alias to <<<DIR>>>): similar to the <<<JAR>>> layout using <<<PropertiesLauncher>>>.

    * <<<MODULE>>>: Bundle dependencies (excluding those with <<<provided>>> scope) and project resources.
      Does not bundle a bootstrap loader.

    * <<<NONE>>>: Bundle all dependencies and project resources. Does not bundle a bootstrap loader.

    []

  For more detailed examples of how to configure this goal see:

    * {{{./examples/repackage-classifier.html}Custom repackage classifier}}

    * {{{./examples/exclude-dependency.html}Exclude a dependency}}

	[]

* 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 the application is executed directly from the Maven JVM. If you need to run
  in a forked process you can use the 'fork' option. Forking will also occur if the
  'jvmArguments' or 'agent' options are specified, or if devtools is present.

  If you need to specify some JVM arguments (i.e. for debugging purposes), you can use
  the <<<jvmArguments>>> parameter, see {{{./examples/run-debug.html}Debug the application}}
  for more details. As a convenience, the profiles to enable are handled by a specific
  property (<<<profiles>>>), see {{{./examples/run-profiles.html}Specify active profiles}}.

  Spring Boot 1.3 has introduced <<<devtools>>>, a module to improve the development-time
  experience when working on Spring Boot applications. To enable it, just add the following
  dependency to your project:

---
<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <version>${project.version}</version>
    <optional>true</optional>
  </dependency>
</dependencies>
---

  When <<<devtools>>> is running, it detects change when you recompile your application and
  automatically refreshes it. This works for not only resources but code as well. It also
  provides a LiveReload server so that it can automatically trigger a browser refresh whenever
  things change.

  Devtools can also be configured to only refresh the browser whenever a static resource has
  changed (and ignore any change in the code). Just include the following property in your
  project:

---
spring.devtools.remote.restart.enabled=false
---

  Prior to <<<devtools>>>, the plugin supported hot refreshing of resources by default which has
  now be disabled in favour of the solution described above. You can restore it at any time by
  configuring your project:

---
<build>
  ...
  <plugins>
    ...
    <plugin>
      <groupId>${project.groupId}</groupId>
      <artifactId>${project.artifactId}</artifactId>
      <version>${project.version}</version>
      <configuration>
        <addResources>true</addResources>
      </configuration>
    </plugin>
    ...
  </plugins>
  ...
</build>
---

  When <<<addResources>>> is enabled, any <<src/main/resources>> folder will be added to
  the application classpath when you run the application and any duplicate found in
  <<target/classes>> will be removed. This allows hot refreshing of resources which can be very
  useful when developing web applications. For example, you can work on HTML, CSS or JavaScript
  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.

  Note that a side effect of using this feature is that filtering of resources at build time will
  not work.

  In order to be consistent with the <<<repackage>>> goal, the <<<run>>> goal builds the classpath
  in such a way that any dependency that is excluded in the plugin's configuration gets excluded
  from the classpath as well. See {{{./examples/exclude-dependency.html}Exclude a dependency}} for
  more details.

  Sometimes it is useful to include test dependencies when running the application. For example,
  if you want to run your application in a test mode that uses stub classes. If you wish to do this,
  you can set the <<<useTestClasspath>>> parameter to true. Note that this is only applied when you
  run an application: the <<<repackage>>> goal will not add test dependencies to the resulting JAR/WAR.

* Working with integration tests

  While you may start your Spring Boot application very easily from your test (or test suite) itself,
  it may be desirable to handle that in the build itself. To make sure that the lifecycle of you Spring
  Boot application is properly managed <around> your integration tests, you can use the <<<start>>> and
  <<<stop>>> goals as described below:

---
<build>
  ...
  <plugins>
    ...
    <plugin>
      <groupId>${project.groupId}</groupId>
      <artifactId>${project.artifactId}</artifactId>
      <version>${project.version}</version>
      <executions>
        <execution>
          <id>pre-integration-test</id>
          <goals>
            <goal>start</goal>
          </goals>
        </execution>
        <execution>
          <id>post-integration-test</id>
          <goals>
            <goal>stop</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
  ...
</build>
---

  Such setup can now use the {{{https://maven.apache.org/surefire/maven-failsafe-plugin/}failsafe-plugin}} to
  run your integration tests as you would expect.

  You could also configure a more advanced setup to skip the integration tests when a specific property has
  been set:

---
<properties>
  <it.skip>false</it.skip>
</properties>
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-failsafe-plugin</artifactId>
      <configuration>
        <skip>${it.skip}</skip>
      </configuration>
    </plugin>
    <plugin>
      <groupId>${project.groupId}</groupId>
      <artifactId>${project.artifactId}</artifactId>
      <version>${project.version}</version>
      <executions>
        <execution>
          <id>pre-integration-test</id>
          <goals>
            <goal>start</goal>
          </goals>
          <configuration>
            <skip>${it.skip}</skip>
          </configuration>
        </execution>
        <execution>
          <id>post-integration-test</id>
          <goals>
            <goal>stop</goal>
          </goals>
          <configuration>
            <skip>${it.skip}</skip>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
---

  If you run <<<mvn verify -Dit.skip=true>>> your integration tests will be skipped altogether.


  For more detailed examples of how to configure this goal see:

    * {{{./examples/it-random-port.html}Random port for integration tests}}

    []
