Chapter 4. Using Thorntail Maven Plugin

Thorntail provides a Maven plugin to accomplish most of the work of building uberjar packages.

4.1. Thorntail Maven plugin general usage

The Thorntail Maven plugin is used like any other Maven plugin, that is through editing the pom.xml file in your application and adding a <plugin> section: 

<plugin>
  <groupId>io.thorntail</groupId>
  <artifactId>thorntail-maven-plugin</artifactId>
  <version>${version.thorntail}</version>
  <executions>
    ...
    <execution>
      <goals>
        ...
      </goals>
      <configuration>
        ...
      </configuration>
    </execution>
  </executions>
</plugin>

4.2. Thorntail Maven plugin goals

The Thorntail Maven plugin provides several goals:

package
Creates the executable package (see Section 9.2, “Creating an uberjar”).
run
Executes your application in the Maven process. The application is stopped if the Maven build is interrupted, for example when you press Ctrl + C.
start and multistart
Executes your application in a forked process. Generally, it is only useful for running integration tests using a plugin, such as the maven-failsafe-plugin. The multistart variant allows starting multiple Thorntail–built applications using Maven GAVs to support complex testing scenarios.
stop

Stops any previously started applications.

Note

The stop goal can only stop applications that were started in the same Maven execution.

4.3. Thorntail Maven plugin configuration options

The Thorntail Maven plugin accepts the following configuration options:

bundleDependencies

If true, dependencies are included in the -thorntail.jar file. Otherwise, they are resolved from $M2_REPO or from the network at runtime.

Property

thorntail.bundleDependencies

Default

true

Used by

package

debug

The port to use for debugging. If set, the Thorntail process suspends on start and opens a debugger on this port.

Property

thorntail.debug.port

Default

 

Used by

run, start

environment

A properties-style list of environment variables to use when executing the application.

Property

none

Default

 

Used by

multistart, run, start

environmentFile

A .properties file with environment variables to use when executing the application.

Property

thorntail.environmentFile

Default

 

Used by

multistart, run, start

filterWebInfLib

If true, the plugin removes artifacts that are provided by the Thorntail runtime from the WEB-INF/lib directory of the project WAR file. Otherwise, the contents of WEB-INF/lib remain untouched.

Property

thorntail.filterWebInfLib

Default

true

Used by

package

Note

This option is generally not necessary and is provided as a workaround in case the Thorntail plugin removes a dependency required by the application. When false, it is the responsibility of the developer to ensure that the WEB-INF/lib directory does not contain Thorntail artifacts that would compromise the functionality of the application. One way to do that is to avoid expressing dependencies on fractions and rely on auto-detection or by explicitly listing any required extra fractions using the fractions option.

fractionDetectMode

The mode of fraction detection. The available options are:

  • when_missing: Runs only when no Thorntail dependencies are found.
  • force: Always run, and merge any detected fractions with the existing dependencies. Existing dependencies take precedence.
  • never: Disable fraction detection.

Property

thorntail.detect.mode

Default

when_missing

Used by

package, run, start

fractions

A list of extra fractions to include when using auto-detection. It is useful for fractions that cannot be detected or for user-provided fractions.

Use one of the following formats when specifying a fraction: * group:artifact:version * artifact:version * artifact

If no group is provided, io.thorntail is assumed.

If no version is provided, the version is taken from the Thorntail BOM for the version of the plugin you are using.

If the value starts with a ! character, the corresponding auto-detected fraction is not installed (unless it is a dependency of any other fraction). In the following example the Undertow fraction is not installed even though your application references a class from the javax.servlet package: 

<plugin>
  <groupId>io.thorntail</groupId>
  <artifactId>thorntail-maven-plugin</artifactId>
  <version>${version.thorntail}</version>
  <executions>
    <execution>
      <goals>
        <goal>package</goal>
      </goals>
      <configuration>
       <fractions>
         <fraction>!undertow</fraction>
       </fractions>
      </configuration>
    </execution>
  </executions>
</plugin>

Property

none

Default

 

Used by

package, run, start

jvmArguments

A list of <jvmArgument> elements specifying additional JVM arguments (such as -Xmx32m).

Property

thorntail.jvmArguments

Default

 

Used by

multistart, run, start

modules

Paths to a directory containing additional module definitions.

Property

none

Default

 

Used by

package, run, start

processes

Application configurations to start (see multistart).

Property

none

Default

 

Used by

multistart

properties

See Section 4.4, “Thorntail Maven plugin configuration properties”.

Property

none

Default

 

Used by

package, run, start

propertiesFile

See Section 4.4, “Thorntail Maven plugin configuration properties”.

Property

thorntail.propertiesFile

Default

 

Used by

package, run, start

stderrFile

Specifies the path to a file where the stderr output is stored instead of being sent to the stderr output of the launching process.

Property

thorntail.stderr

Default

 

Used by

run, start

stdoutFile

Specifies the path to a file where the stdout output is stored instead of being sent to the stdout output of the launching process.

Property

thorntail.stdout

Default

 

Used by

run, start

useUberJar

If specified, the -thorntail.jar file located in ${project.build.directory} is used. This JAR is not created automatically, so make sure you execute the package goal first.

Property

thorntail.useUberJar

Default

 

Used by

run, start

4.4. Thorntail Maven plugin configuration properties

Properties can be used to configure the execution and affect the packaging or running of your application.

If you add a <properties> or <propertiesFile> section to the <configuration> of the plugin, the properties are used when executing your application using the mvn thorntail:run command. In addition to that, the same properties are added to your myapp-thorntail.jar file to affect subsequent executions of the uberjar. Any properties loaded from the <propertiesFile> override identically-named properties in the <properties> section.

Any properties added to the uberjar can be overridden at runtime using the traditional -Dname=value mechanism of the java binary, or using the YAML-based configuration files.

Only the following properties are added to the uberjar at package time:

  • The properties specified outside of the <properties> section or the <propertiesFile>, whose path starts with one of the following:

    • jboss.
    • wildfly.
    • thorntail.
    • swarm.
    • maven.
  • The properties that override a property specified in the <properties> section or the <propertiesFile>.