Maven Plugin

To assist in building WildFly Swarm projects, a Maven plugin is available. This plugin creates the -swarm.jar uberjar which contains your application along with the necessary parts of WildFly to support it.

Configuration

To use the plugin, you must add it to your pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>wildfly-swarm-plugin</artifactId>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Packaging your application

Default uberjar

To produce the myapp-swarm.jar, simply perform a typical mvn package command after setting the package goal on the plugin:

mvn package

Hollow uberjar

To produce a hollow uberjar, the same mvn package method is used, but either set the property -Dswarm.hollow=true or configure the plugin with <hollow>true</hollow> from within your pom.xml.

A hollow uberjar will have the suffix of -hollowswarm.jar and will not include the actual application deployment. This may be useful if you are targetting layered Linux containers, where you wish to place the runtime on a lower layer, and the more frequently changing deployment on a higher layer.

If using the hollow functionality, the command-line arguments to the uberjar shouldl point to one or more deployments that should be used.

java -jar myruntime-hollowjar.jar myapp.war

An example of the hollow jar functionality may be seen in the MicroProfile standalone server.

Running your application

To execute your application, you may use the wildfly-swarm:run goal:

mvn wildfly-swarm:run

This will execute your application within the WildFly Swarm runtime directly from the Maven command-line, and wait for it to exit.

Both of these goals will perform the same type of fraction detection as the package task if no WildFly Swarm dependencies are found.

Fraction detection

If the plugin doesn’t detect any WildFly Swarm dependencies in your pom.xml, it will attempt to auto-detect needed fractions by scanning the application. This is mostly useful for WAR-based applications that you are migrating to WildFly Swarm - you only need to add the plugin to your configuration, and not any other WildFly Swarm dependencies. You can control fraction detection by setting <fractionDetectMode>. See the configuration options below for more details.

Plugin Configuration Options

The plugin accepts the following options:

Name Property Description Default Used by

bundleDependencies

swarm.bundleDependencies

If true, dependencies will be included in the -swarm.jar. Otherwise, they will be resolved from $M2_REPO or the network at runtime.

true

package

debug

none

A port to use for debugging. If set, the swarm process will suspend on start and open a debugger on this port.

run, start

environment

none

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

multistart, run, start

environmentFile

swarm.environmentFile

A .properties file of environment variables to use when running the application

multistart, run, start

fractionDetectMode

swarm.fractionDetectMode

The mode for fraction detection. Options are: * when_missing: runs only when no WildFly Swarm dependencies are found * force: always run, and merge any detected fractions with the existing dependencies, with existing dependencies taking precedence * never: disable fraction detection

when_missing

package, run, start

fractions

none

A list of extra fractions to include when auto-detection is used, useful for fractions that can’t be detected or user-provided fractions. Each fraction can be of the form group:name:version, name:version, or name. If no group is provided, org.wildfly.swarm is assumed. If no version is provided, the version is looked up from the WildFly Swarm BOM for the version of the plugin you are using.

package, run, start

hollow

swarm.hollow

Boolean specifying if the resulting executable jar should be hollow and not include the default deployment.

false

multistart, run, start

jvmArguments

swarm.jvmArguments

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

multistart, run, start

mainClass

swarm.mainClass

A class to execute as the main

org.wildfly.swarm.bootstrap.Main

package, run, start

modules

none

Paths to a directory containing additional module definitions

./modules

package, run, start

processes

none

Application configurations to start (see multistart section above)

multistart

properties

none

(see properties section below)

package, run, start

propertiesFile

swarm.propertiesFile

(see properties section below)

package, run, start

stderrFile

swarm.stderr

A file path to use to store stderr output instead of sending it stderr of the launching process

run, start

stdoutFile

swarm.stdout

A file path to use to store stdout output instead of sending it stdout of the launching process

run, start

useUberJar

swarm.useUberJar

If true, the -swarm.jar from ${project.build.directory} will be used. This jar will not be automatically created, so the package goal will need to have already been executed.

false

run, start

Properties

Many properties may be used to configure 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 will be used when running your application via mvn wildfly-swarm:run. Additionally, those same properties will be added to your myapp-swarm.jar to affect subsequent executions of the uberjar. Any properties loaded from <propertiesFile> will override same-named properties from <properties>.

Any properties added to the uberjar can of course be overridden at runtime using the traditional -Dname=value mechanism of java.

Only properties specified outside of <properties> or <propertiesFile> that start with jboss., wildfly., swarm., or maven., or override a property specified in <properties> or <propertiesFile> are added to the uberjar at package time.

Please see Configuration Properties for a non-exhaustive list of useful properties.