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

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

mvn package

Example

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>wildfly-swarm-plugin</artifactId>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <bundleDependencies>false</bundleDependencies>
        <properties>
          <swarm.bind.address>127.0.0.1</swarm.bind.address>
        </properties>
      </configuration>
    </plugin>
  </plugins>
</build>

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.

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. If you want to start the application without maven waiting for it to exit, use the wildfly-swarm:start goal.

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

Starting multiple applications at once

You can start multiple swarm applications at once using the wildfly-swarm:multistart goal (this is useful for integration testing a set of applications). Each application is specified as a <process> containing an optional <groupId>, an <artifactId>, and an optional <executionId> (useful if you need to launch multiple copies of the same application). Each <process> can also include any configuration that is valid for the wildfly-swarm:start goal.

Example

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>wildfly-swarm-plugin</artifactId>
      <executions>
        <execution>
          <id>multistart</id>
          <phase>pre-integration-test</phase>
          <goals>
            <goal>multistart</goal>
          </goals>
          <configuration>
            <processes>
              <process>
                <artifactId>my-frontend-app</artifactId>
              </process>
              <process>
                <artifactId>my-auth-app</artifactId>
                <properties>
                  <swarm.http.port>8081</swarm.http.port>
                </properties>
                <mainClass>com.example.auth.Main</mainClass>
              </process>
              <process>
                <artifactId>my-indexing-app</artifactId>
                <properties>
                  <swarm.http.port>8082</swarm.http.port>
                </properties>
                <environment>
                  <ENV>test</ENV>
                </environment>
              </process>
            </processes>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Stopping started applications

If you have started any applications with either wildfly-swarm:start or wildfly-swarm:multistart, they can be stopped by executing the wildfly-swarm:stop goal.

Configuration Options

The plugin accepts the following options:

Name Description Default Used by

bundleDependencies

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

true

package

debug

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

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

multistart, run, start

environmentFile

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

multistart, run, start

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

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

jvmArguments

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

multistart, run, start

mainClass

A class to execute as the main

org.wildfly.swarm.bootstrap.Main

package, run, start

modules

Paths to a directory containing additional module definitions

./modules

package, run, start

processes

Application configurations to start (see multistart section above)

multistart

properties

(see properties section below)

package, run, start

propertiesFile

(see properties section below)

package, run, start

stderrFile

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

run, start

stdoutFile

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

run, start

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.