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 local Maven repository or from the network at runtime.

Property

thorntail.bundleDependencies

Default

true

Used by

package

Note

In case you set bundleDependencies to false, a local Maven repository is used at runtime. The location of the Maven repository is retrieved either from a settings.xml file, or from a system property.

  1. If a settings.xml file is found and it defines a local repository, then this repository is used. The following locations are searched for the settings.xml file. The first occurrence of the file is used to retrieve the location of the Maven repository:

    1. If the jboss.modules.settings.xml.url system property is defined, then the settings.xml file defined in this property is used. The value must be a file://... URL .
    2. If the ~/.m2/settings.xml file exists, then it is used.
    3. If the $M2_HOME/conf/settings.xml file exists, then it is used.

  2. If the path to the Maven repository is not defined in a settings.xml file, then:

    1. If the maven.repo.local system property is defined, then this repository is used.
    2. Otherwise the standard location ~/.m2/repository is used.
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. If uberjar-only, this transformation is only done on the WAR file that is put into the uberjar, and the standalone WAR file remains untouched. 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>.