WildFly Galleon Plugins Documentation

1. Introduction

WildFly Galleon Plugins project includes Galleon plugin and Maven plugin implementations that are dedicated to building feature-packs (including generation of feature specs, packages and other resources) for WildFly releases and provisioning of WildFly-based distributions. These plugins can also be used by projects that integrate into or extend WildFly.

1.1. Maven plugins

This Maven tooling allows to build feature-packs that can be combined with WildFly feature-packs to produce customized WildFly server installations.

The Maven plugin "org.wildfly.galleon:wildfly-galleon-maven-plugin" exposes 2 goals:

build-feature-pack: A goal to be used by WildFly developers when defining WildFly feature-packs that implement new WidFly subsystems and expose new server capabilities.
build-user-feature-pack: A goal to be used by WildFly server users in order to define new Layers, new JBoss Modules, … that depend on existing WildFly subsystems and capabilities.

1.2. Galleon plugins

During provisioning, a WildFly specific Galleon plugin is executed to install the WildFly server. This plugin can be configured with a set of options in order to tune the WildFly server installation. The way to provide these options is tool specific.

For the Galleon CLI command line tool: the options are exposed using completion (TAB key) for the install command. Options can also be set in the provisioning.xml file when using the provision command. A provisioning.xml file example:

<installation xmlns="urn:jboss:galleon:provisioning:3.0">
    <feature-pack location="wildfly@maven(org.jboss.universe:community-universe):current"/>
    <options>
        <option name="jboss-fork-embedded" value="false"/>
        <option name="jboss-maven-dist"/>
    </options>
</installation>

For the Galleon Maven plugin configuration: The <plugin-options> element contains the options as XML elements. For example:

<configuration>
...
 <plugin-options>
  <jboss-fork-embedded>true</jboss-fork-embedded>
 </plugin-options>
...
</configuration>

For the WildFly Maven plugin configuration: The <galleon-options> element contains the options as XML elements. For example:

<configuration>
...
 <galleon-options>
  <jboss-fork-embedded>true</jboss-fork-embedded>
 </galleon-options>
...
</configuration>

For the WildFly Bootable JAR Maven plugin configuration: The <plugin-options> element contains the options as XML elements. For example:

<configuration>
...
 <plugin-options>
  <jboss-fork-embedded>true</jboss-fork-embedded>
 </plugin-options>
...
</configuration>

For the prospero tool, you can define a provisioning.xml file that contains the options. A provisioning.xml file example:

<installation xmlns="urn:jboss:galleon:provisioning:3.0">
    <feature-pack location="wildfly@maven(org.jboss.universe:community-universe):current"/>
    <options>
        <option name="jboss-fork-embedded" value="false"/>
        <option name="jboss-maven-dist"/>
    </options>
</installation>

1.2.1. Installation Plugin options

Option

Type

Default value

Description

jboss-bulk-resolve-artifacts

Boolean

false

Maven artifacts that are needed for the WildFly server installation are resolved in a bulk operation instead of being resolved individually. That can speed-up the provisioning time.

jboss-dump-config-scripts

String

NONE

A path to a directory in which WildFly CLI script files used to generate the server configurations are stored.

jboss-fork-embedded

Boolean

false

Fork in a separate process the generation of the server configuration files. Server configuration generation implies the usage of a WildFly Embedded server. It is advised to set this env variable to true, specially when having multiple executions of the provisioning inside the same process (e.g.: multiple executions of Galleon|WildFly|Bootable JAR Maven plugins).

jboss-maven-dist

Boolean

false

Provision a thin WildFly server installation with JBoss Modules modules jar resolved from Maven local cache and not copied to the modules directory.

jboss-maven-repo

String

NONE

A path to a directory in which all the resolved Maven artifacts jars and associated pom files are stored. The generated directory complies with the filesystem layout of a Maven repository. This respository can then be used as the local cache of a thin WildFly server (see jboss-maven-dist option).

jboss-overridden-artifacts

'|' separated list of maven coordinates in the following syntax: GroupId:ArtifactId:Version:[Classifier:]Extension

NONE

A list of Maven artifact coordinates used to override the artifact versions that are defined in the provisioned WildFly feature-pack. For example, to override undertow-core: io.undertow:undertow-core:2.3.1.Final::jar

jboss-reset-embedded-system-properties

Comma-separated list of String

NONE

When executing a forked process to generate the server configuration, all system properties defined in the parent process are inherited by the forked process. Setting this property to an empty value will reset the system properties used by WildFly server during startup. To reset WildFly specific system properties and some additional properties, add to the comma-separated list the names of system property to reset. To not reset a WildFly specific system property, add the property name prefixed with - to the list.

jboss-resolved-artifacts-cache

String

NONE

A path to a directory where to cache the resolved Maven artifacts that are not part of the server installation (feature-packs, Galleon plugins, …). NOTE: This option is specific to the usage of the prospero provisioning tool.

2. Building a custom feature-pack example

Defining your own Galleon feature-packs allow you to create customized WildFly server installation containing your custom content and trimmed to your need. In this example we are seeing how to setup a Maven project to create a Galleon feature-pack that contains Galleon layers to install static web content, a JDBC driver and a datasource.

2.1. Setting up Maven project

Call the following command to create an empty Maven project:

mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes \
-DarchetypeArtifactId=pom-root -DgroupId=org.example.demo \
-DartifactId=my-custom-galleon-pack -DinteractiveMode=false

N.B.: The type of packaging of your pom.xml project file must be <packaging>pom</packaging>.

Add the Maven plugin dependency in your pom.xml file :

<dependencies>
  <dependency>
    <groupId>org.wildfly.galleon-plugins</groupId>
    <artifactId>wildfly-galleon-maven-plugin</artifactId>
    <version>7.0.0.Final</version>
  </dependency>
</dependencies>

Integrate the plugin in your build element:

 <build>
   <plugins>
     <plugin>
       <groupId>org.wildfly.galleon-plugins</groupId>
       <artifactId>wildfly-galleon-maven-plugin</artifactId>
       <executions>
         <execution>
           <id>myproject-galleon-pack-build</id>
           <goals>
             <goal>build-user-feature-pack</goal>
           </goals>
           <phase>compile</phase>
         </execution>
       </executions>
     </plugin>
   </plugins>
 </build>

2.2. Expressing a dependency on WildFly

A feature-pack has a dependency on WildFly feature-pack, this dependency is resolved from the project pom file. Add the WildFly Galleon feature-pack dependency to the project dependencies section:

<dependency>
  <groupId>org.wildfly</groupId>
  <artifactId>wildfly-galleon-pack</artifactId>
  <version>26.0.0.Final</version>
  <type>zip</type>
</dependency>

Expressing a dependency on WildFly 26.0.0.Final doesn’t mean that the feature-pack is limited to be used in conjunction with WildFly 26.0.0.Final. When provisioning your feature-pack with a WildFly feature-pack, the version of the WildFly feature-pack present in the provisioning will get used. This means that your feature-pack is usable with future WildFly release (WildFly guarantee backward compatibility there).

2.3. Source structure

Create the directory src/main/resources, it will contain the content of your feature-pack. The resources directory can contain the following sub-directories:

configs: contains default configurations provided by this feature-pack.
feature_groups: contains feature groups, a reusable unit that contains the server configuration content that can then be referenced from layers and configurations.
layers: contains layers, a layer reflects the content and configuration of a WildFly server capability that are provisioned when the layer is used.
modules: contains JBoss Modules modules you want to see packaged in the feature-pack. JBoss Modules modules can then be referenced from layers and configurations.
packages: contains packages, a package contains content you want to see installed in the server (eg: properties files, keystores, tools, scripts,…).

In this example we are adding feature_groups, layers, modules and packages to our custom WildFly feature-pack.

2.4. Defining JBoss Modules modules

JBoss Modules modules can be referenced from Galleon layers and/or feature-groups using the module name. e.g.: org.mariadb.jdbc.

Under the modules directory create a directory path identical to the one we would find under the JBOSS_HOME/modules directory.

For this example create the directory src/main/resources/modules/org/mariadb/jdbc/main that will contain the module.xml file. NB: The actual JAR files that implement the module are NOT packaged inside the feature-pack, the JAR files are retrieved from Maven at provisioning time.

The module.xml file content is:

<?xml version="1.0" encoding="UTF-8"?>
<module name="org.mariadb.jdbc" xmlns="urn:jboss:module:1.8">
   <resources>
       <!-- Expression to retrieve the mariadb driver artifact from Maven. The version must be expressed in the feature-pack pom.xml dependencies-->
       <artifact name="${org.mariadb.jdbc:mariadb-java-client}"/>
   </resources>
   <!-- The JDBC driver depends on the following API -->
   <dependencies>
       <module name="javax.api"/>
       <module name="javax.transaction.api"/>
   </dependencies>
</module>

The pom.xml of your feature-pack project must also contain the actual dependency on the org.mariadb.jdbc:mariadb-java-client Maven artifact.

Add the following dependency to the project dependencies:

<dependency>
  <groupId>org.mariadb.jdbc</groupId>
  <artifactId>mariadb-java-client</artifactId>
  <version>2.7.2</version>
</dependency>

We are done defining the org.mariadb.jdbc JBoss Modules module. This module will get installed when the Galleon layer that references it is used. We will see that later when provisioning the custom feature-pack.

2.5. Defining packages

For each package you are defining, under the directory src/main/resources/packages/ create a directory with the name of the package. The usual package directory structure is:

packages/<package_name>
|- content/
|- pm/
|  `- wildfly/
|     `- tasks.xml
`- package.xml

The file package.xml is required, it contains the package name. Optionally it can contain the dependencies on other packages that would get installed when this package is provisioned.

XML syntax for the package.xml is covered by this XML schema.

Create the directory src/main/resources/packages/my-web-server-content.

The file src/main/resources/packages/my-web-server-content/package.xml content is:

<?xml version="1.0" ?>
<package-spec xmlns="urn:jboss:galleon:package:2.0" name="my-web-server-content"/>

The content directory includes content that will be copied to the installation root directory when the package is installed.

Create the directory src/main/resources/packages/my-web-server-content/content/my-web-server-content. It will contain our static web content.

Create the file src/main/resources/packages/my-web-server-content/content/my-web-server-content/index.html:

<html>
<body>
<h1>Hello World</h1>
</body>
</html>

Create the file src/main/resources/packages/my-web-server-content/content/my-web-server-content/Error404.html:

<html>
<body>
<h1>Resource not found!</h1>
</body>
</html>

When the package my-web-server-content is provisioned (because referenced from a Galleon layer), the directory my-web-server-content will get installed in the server.

pm/wildfly/tasks.xml file is optional, it may include instructions to copy and/or delete files and directories, create directories, resolve and copy Maven artifacts to the installation directory, etc. These tasks are executed when the content of all the packages has been copied into the installation.

The tasks XML schema contains the definition of the tasks you can add to the tasks.xml file. This example of tasks.xml file contains the set of tasks one can use in a tasks.xml file.

In the context of this example we don’t need to define a tasks.xml file.

2.6. Defining layers

One powerful aspect of Galleon are layers. By provisioning layers you can create a trimmed WildFly server containing only the set of features (server configuration and JBoss Modules modules) required by your application.

WildFly comes with a set of Galleon layers that allows you to provision a trimmed server containing subsystems configured in a way that is nearly identical to the default configuration (as found in standalone*.xml configuration).

In order to fine tune the trimmed server configuration, WildFly CLI tool can be an approach. Running CLI scripts imply to execute the CLI tool on each provisioned server instance.

By defining your own Galleon layers, you can provision a server already fully configured without the need for extra CLI script execution.

XML syntax for layers is covered by this XML schema.

A layer allows you to package inside a single artifact (the layer) some server configuration item (eg: subsystem configuration) and content (eg: JBoss Modules modules).

A good example is the JDBC driver. When adding a JDBC driver to a wildfly installation we are generally updating the datasources subsystem and add a JBoss Module module.

Now for each layer you are defining, create a directory with the name of the layer. Each directory contains a single file named layer-spec.xml that contains the actual content of the layer.

2.6.1. `my-undertow-handler` layer example

This layer configures undertow subsystem to serve the static content, sets a 404 handler and references the my-web-server-content package.

Create the directory src/main/resources/layers/standalone/my-undertow-handler.

Create the file src/main/resources/layers/standalone/my-undertow-handler/layer-spec.xml with the following content:

<?xml version="1.0" ?>
<layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="my-undertow-handler">
  <!-- features are added to the server configuration -->
  <feature spec="subsystem.undertow.server">
    <param name="server" value="default-server" />
    <feature spec="subsystem.undertow.server.host">
       <param name="host" value="default-host" />
       <feature spec="subsystem.undertow.server.host.location">
         <param name="location" value="/web"/>
         <param name="handler" value="my-web-server-content"/>
       </feature>
       <feature spec="subsystem.undertow.server.host.filter-ref">
         <param name="filter-ref" value="404-handler"/>
         <param name="predicate" value="true"/>
       </feature>
    </feature>
  </feature>
  <feature spec="subsystem.undertow.configuration.handler.file">
    <param name="file" value="my-web-server-content"/>
    <param name="path" value="${jboss.home.dir}/my-web-server-content"/>
    <param name="directory-listing" value="true"/>
  </feature>
  <feature spec="subsystem.undertow.configuration.filter.error-page">
    <param name="error-page" value="404-handler"/>
    <param name="code" value="404"/>
    <param name="path" value="${jboss.home.dir}/my-web-server-content/Error404.html"/>
  </feature>

  <!-- Packages content is installed inside the server -->
  <packages>
    <package name="my-web-server-content"/>
  </packages>
</layer-spec>

You will notice that a layer contains feature. You can see features as server Management resources. The spec attribute can be derived from the resource path used in JBoss CLI commands. The following CLI operations would have the same effect than the features instantiated in this layer:

/subsystem=undertow/configuration=handler/file=my-web-server-content:add(path="${jboss.home.dir}/my-web-server-content", directory-listing=true)
/subsystem=undertow/configuration=filter/error-page=404-handler:add(path="${jboss.home.dir}/my-web-server-content/Error404.html", code=404)
/subsystem=undertow/server=default-server/host=default-host/location="/web":add(handler=my-web-server-content)
/subsystem=undertow/server=default-server/host=default-host/filter-ref=404-handler:add(predicate=true)

2.6.2. `mariadb-driver` layer example

This layer contains the configuration for a mariadb JDBC driver.

Create the directory src/main/resources/layers/standalone/mariadb-driver.

Create the file src/main/resources/layers/standalone/mariadb-driver/layer-spec.xml with the following content:

<?xml version="1.0" ?>
<layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="mariadb-driver">
  <!-- Add the driver to the datasources subsystem -->
  <feature spec="subsystem.datasources">
    <feature spec="subsystem.datasources.jdbc-driver">
      <param name="driver-name" value="mariadb"/>
      <param name="jdbc-driver" value="mariadb"/>
      <param name="driver-xa-datasource-class-name" value="org.mariadb.jdbc.MariaDbDataSource"/>
      <param name="driver-module-name" value="org.mariadb.jdbc"/>
    </feature>
  </feature>

  <!-- Will install the JBoss Modules org.mariadb.jdbc module. -->
  <packages>
    <package name="org.mariadb.jdbc"/>
  </packages>
</layer-spec>

The following CLI operations would have the same effect than the features instantiated in this layer:

/subsystem=datasources/jdbc-driver=mariadb:add(driver-name=mariadb, \
driver-module-name=org.mariadb.jdbc, \
driver-xa-datasource-class-name=org.mariadb.jdbc.MariaDbDataSource)

2.6.3. `mariadb-datasource` layer example

A layer that adds a MariaDBDS datasource that is bound to the mariadb driver. This layer adds the ability to configure the datasource (host, port, database, username, password) thanks to environment variables that can be be set at server run-time.

Create the directory src/main/resources/layers/standalone/mariadb-datasource.

Create the file src/main/resources/layers/standalone/mariadb-datasource/layer-spec.xml with the following content:

<?xml version="1.0" ?>
<layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="mariadb-datasource">

  <!-- express a dependency on the driver layer to have it automatically provisioned when mariadb-datasource is provisioned -->
  <dependencies>
    <layer name="mariadb-driver"/>
  </dependencies>

  <feature spec="subsystem.datasources.data-source">
    <param name="data-source" value="MariaDBDS"/>
    <param name="jndi-name" value="java:jboss/datasources/${env.MARIADB_DATASOURCE:MariaDBDS}"/>
    <param name="connection-url" value="jdbc:mariadb://${env.MARIADB_HOST:localhost}:${env.MARIADB_PORT:3306}/${env.MARIADB_DATABASE}"/>
    <param name="driver-name" value="mariadb"/>
    <param name="user-name" value="${env.MARIADB_USER}"/>
    <param name="password" value="${env.MARIADB_PASSWORD}"/>
  </feature>
</layer-spec>

The following CLI operations would have the same effect than what we have expressed in this layer:

/subsystem=datasources/data-source=MariaDBDS:add(jndi-name="java:jboss/datasources/${env.MARIADB_DATASOURCE:MariaDBDS}", \
connection-url="jdbc:mariadb://${env.MARIADB_HOST:localhost}:${env.MARIADB_PORT:3306}/${env.MARIADB_DATABASE}", \
driver-name=mariadb, user-name="${env.MARIADB_USER}", password="${env.MARIADB_PASSWORD}")

2.7. Defining feature groups

XML syntax for feature-groups is covered by this XML schema.

A feature-group is contained inside an xml file located inside the src/main/resources/feature_groups. The XML file name is the name of the feature-group.

A feature-group allows you to group feature instantiation inside a group that can then be referenced from other groups or layers.

We could have chosen to define the undertow handler in a feature group and reference it from the layer.

The content of the src/main/resources/feature_groups/my-undertow-handler-grp.xml feature-group would look like:

<?xml version="1.0" ?>

<feature-group-spec name="my-undertow-handler-grp" xmlns="urn:jboss:galleon:feature-group:1.0">
  <!-- features are added to the server configuration -->
  <feature spec="subsystem.undertow.server">
    <param name="server" value="default-server" />
    <feature spec="subsystem.undertow.server.host">
       <param name="host" value="default-host" />
       <feature spec="subsystem.undertow.server.host.location">
         <param name="location" value="/web"/>
         <param name="handler" value="my-web-server-content"/>
       </feature>
       <feature spec="subsystem.undertow.server.host.filter-ref">
         <param name="filter-ref" value="404-handler"/>
         <param name="predicate" value="true"/>
       </feature>
    </feature>
  </feature>
  <feature spec="subsystem.undertow.configuration.handler.file">
    <param name="file" value="my-web-server-content"/>
    <param name="path" value="${jboss.home.dir}/my-web-server-content"/>
    <param name="directory-listing" value="true"/>
  </feature>
  <feature spec="subsystem.undertow.configuration.filter.error-page">
    <param name="error-page" value="404-handler"/>
    <param name="code" value="404"/>
    <param name="path" value="${jboss.home.dir}/my-web-server-content/Error404.html"/>
  </feature>

  <!-- Packages content is installed inside the server -->
  <packages>
    <package name="my-web-server-content"/>
  </packages>
</feature-group-spec>

Then, from the my-undertow-handler layer, we could have referenced the feature-group instead of the features:

<?xml version="1.0" ?>

<layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="my-undertow-handler">
  <feature-group name="my-undertow-handler-grp"/>
</layer-spec>

2.8. Building your feature-pack

This is done by calling mvn clean install in the maven project. A zip artifact org.example.demo:my-custom-galleon-pack:1.0-SNAPSHOT is built and installed in the maven local cache. This feature-pack artifact is what will get used when provisioning a WildFly server.

2.9. Making your feature-pack available

For local development and testing, having the feature-pack installed in the Maven local cache is all what you need. In order to share your feature-pack, it has to be deployed in remote Maven repositories.

2.10. Provisioning your feature-pack

The same feature-pack can be used to provision a server using different tooling. Usage is not limited to bare-metal, feature-packs can be used to provision custom WildFly server on the cloud. Main tools to provision custom WildFly servers are:

2.10.1. WildFly Bootable JAR Maven plugin

We will not go into all the details of how to provision a Bootable JAR, the Bootable JAR documentation covers it in detail. We are here showing plugin configuration extract in which we are referencing our custom feature-pack and layers.

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-jar-maven-plugin</artifactId>
    <configuration>
        <feature-packs>
            <!-- the List of feature-packs to use during provisioning. Always provide WildFly feature-pack as the first one. -->
            <feature-pack>
                <groupId>org.wildfly</groupId>
                <artifactId>wildfly-galleon-pack</artifactId>
                <version>26.0.0.Final</version>
            </feature-pack>
            <!-- Our custom feature-pack -->
            <feature-pack>
                <groupId>org.example.demo</groupId>
                <artifactId>my-custom-galleon-pack</artifactId>
                <version>1.0-SNAPSHOT</version>
            </feature-pack>
        </feature-packs>
        <!-- Layers in use to provision the server -->
        <layers>
            <!-- WildFly layer that provides web + support for datasources -->
            <layer>datasources-web-server</layer>
            <!-- The custom layers we have defined -->
            <layer>mariadb-datasource</layer>
            <layer>my-undertow-handler</layer>
        </layers>
        ...

2.10.2. WildFly Maven plugin

The configuration of feature-packs and layers is identical to the one we have seen in the Bootable JAR chapter.

3. Maven plugin

This chapter is dedicated to the Maven plugin that can be used to build WildFly-based feature-packs. Maven coordinates of the Maven plugin artifact are

Maven plugin installing feature-packs and provisioning distributions is a part of Galleon project itself. Please, refer to Galleon documentation for more information.

<dependency>
    <groupId>org.wildfly.galleon-plugins</groupId>
    <artifactId>wildfly-galleon-maven-plugin</artifactId>
    <version>7.0.0.Final</version>
</dependency>

3.1. Goals overview

generate-all-artifacts-list

Generates a list of all the artifacts required to install the full version of a feature-pack.

build-user-feature-pack

Creates feature-packs intended to be built on top WildFly feature-packs.

build-feature-pack

Creates a feature-pack archive from the provided resources in the WildFly fashion (used for official WildFly feature-packs).

3.2. generate-all-artifacts-list

3.2.1. wildfly-galleon:generate-all-artifacts-list

Full name: org.wildfly.galleon-plugins:wildfly-galleon-maven-plugin:7.0.0.Final:generate-all-artifacts-list

3.2.2. Description

Aggregate all artifact lists (offliners) of a feature-pack dependencies. In addition adds to the list the feature-pack itself and universe artifacts. The resulting list is attached as an artifact to the current project. If output-licenses-file is set, a license file for the contained artifacts is generated.

3.2.3. Attributes

Requires a Maven project to be executed.
Requires dependency resolution of artifacts in scope: runtime.
Binds by default to the lifecycle phase: compile.

Table 1. Required Parameters
Name	Type	Since	Description
`[fpArtifactId]`	`String`	`-`	(no description) Alias is: `feature-pack-artifact-id`.
`[fpGroupId]`	`String`	`-`	(no description) Alias is: `feature-pack-group-id`.

Table 2. Optional Parameters
Name	Type	Since	Description
`[excludedVersions]`	`String`	`-`	(no description) Alias is: `excluded-licenses-versions`.
`[extraArtifacts]`	`List`	`-`	(no description) Alias is: `extra-artifacts`.
`[fpVersion]`	`String`	`-`	(no description) Alias is: `feature-pack-version`.
`[licensesFile]`	`String`	`-`	(no description) Alias is: `output-licenses-file`.
`[offline]`	`boolean`	`-`	(no description) Default value is: `false`. Alias is: `offline`.

3.2.4. Parameter Details

excludedVersions
(no description)

Type: java.lang.String
Required: No
Alias: excluded-licenses-versions

extraArtifacts
(no description)

Type: java.util.List
Required: No
Alias: extra-artifacts

fpArtifactId
(no description)

Type: java.lang.String
Required: Yes
Alias: feature-pack-artifact-id

fpGroupId
(no description)

Type: java.lang.String
Required: Yes
Alias: feature-pack-group-id

fpVersion
(no description)

Type: java.lang.String
Required: No
Alias: feature-pack-version

licensesFile
(no description)

Type: java.lang.String
Required: No
Alias: output-licenses-file

offline
(no description)

Type: boolean
Required: No
Default: false
Alias: offline

3.3. build-user-feature-pack

3.3.1. wildfly-galleon:build-user-feature-pack

Full name: org.wildfly.galleon-plugins:wildfly-galleon-maven-plugin:7.0.0.Final:build-user-feature-pack

3.3.2. Description

This Maven Mojo is intended to be used to build feature-packs that depend on one of the WildFly feature-packs. This Maven mojo creates a WildFly style feature-pack archive from the provided resources according to the feature-pack build configuration file and attaches it to the current Maven project as an artifact. If no feature-pack build configuration is provided, some defaults are applied. The content of the future feature-pack archive is first created in the directory called feature-pack-layout under the module’s build directory which is then ZIPped to create the feature-pack artifact.

3.3.3. Attributes

Requires a Maven project to be executed.
Requires dependency resolution of artifacts in scope: runtime.
Binds by default to the lifecycle phase: compile.

Table 3. Required Parameters
Name	Type	Since	Description
`[resourcesDir]`	`String`	`-`	Represents the directory containing child directories `packages`, `feature_groups`, `modules` etc. Either an absolute path or a path relative to `configDir`. Default value is: `src/main/resources`. User property is: `wildfly.user.feature.pack.resourcesDir`. Alias is: `resources-dir`.

Table 4. Optional Parameters
Name	Type	Since	Description
`[addFeaturePacksAsRequiredManifests]`	`boolean`	`-`	Add any feature-pack dependency as a required manifest in the manifest YAML definition. This parameter has no effect if "generate-channel-manifest" is false. Default value is: `true`. Alias is: `add-feature-packs-as-required-manifests`.
`[buildName]`	`String`	`-`	The directory for the built artifact. Default value is: `${project.build.directory}`. User property is: `wildfly.user.feature.pack.buildName`.
`[configDir]`	`File`	`-`	The feature-pack build configuration file directory Default value is: `${basedir}`. User property is: `wildfly.user.feature.pack.configDir`. Alias is: `config-dir`.
`[configFile]`	`String`	`-`	The feature-pack build configuration file. Default value is: `wildfly-user-feature-pack-build.xml`. User property is: `wildfly.user.feature.pack.configFile`. Alias is: `config-file`.
`[configStatibilityLevel]`	`String`	`-`	The default stability level used at provisioning time to generate configuration. Can’t be used when `stability-level` is set. Alias is: `config-stability-level`.
`[deployChannelManifest]`	`boolean`	`-`	(no description) Default value is: `true`. User property is: `wildfly.feature.pack.deploy-channel-manifest`. Alias is: `deploy-channel-manifest`.
`[fpLocation]`	`String`	`-`	The FPL for the generated feature-pack. Default value is: `${project.groupId}:${project.artifactId}:${project.version}`. Alias is: `feature-pack-location`.
`[generateChannelManifest]`	`boolean`	`-`	Generates a channel manifest YAML definition when the feature-pack is produced. Any dependency from the feature pack is declared as a stream in the channel manifest. Default value is: `false`. User property is: `wildfly.feature.pack.generate-channel-manifest`. Alias is: `generate-channel-manifest`.
`[minimumStabilityLevel]`	`String`	`-`	The minimum stability level of the WildFly processes used to generate feature specs and include packages. Set this if you need to generate feature specs for features with a lower stability level than the default level of the WildFly process being used for feature-spec generation. Alias is: `minimum-stability-level`.
`[packageStatibilityLevel]`	`String`	`-`	The default stability level used at provisioning time when installing packages/JBoss Modules modules. Can’t be used when `stability-level` is set. Alias is: `package-stability-level`.
`[releaseName]`	`String`	`-`	The name of the release the feature-pack represents which will be stored in the feature-pack’s `resources/wildfly/wildfly-tasks.properties` as `product.release.name` property. Default value is: `${product.release.name}`. Alias is: `release-name`.
`[stabilityLevel]`	`String`	`-`	The default stability level used at provisioning time to generate configuration and provision packages. Can’t be used when `config-stability-level` or `package-stability-level` is set. Alias is: `stability-level`.
`[taskProps]`	`Map`	`-`	Various properties that will be added to feature-pack’s `resources/wildfly/wildfly-tasks.properties`. NOTE: values of this parameter will overwrite the corresponding values from task-properties-file parameter, in case it’s also set. + Alias is: `task-properties`.
`[taskPropsFile]`	`File`	`-`	Path to a properties file content of which will be added to feature-pack’s `resources/wildfly/wildfly-tasks.properties` file that is used as the source of properties during file copying tasks with property replacement. Alias is: `task-properties-file`.
`[translateToFpl]`	`Boolean`	`-`	By default generated build config dependencies are expressed using GAV, set this parameter to true to generate FPL. Default value is: `false`. Alias is: `translate-to-fpl`.
`[wildflyChannelResolutionMode]`	`WildFlyChannelResolutionMode`	`-`	Feature-pack WildFly channel resolution mode when WildFly channels are configured in the provisioning tooling used to provision this feature-pack. "NOT_REQUIRED" means that the feature-pack and artifacts can be resolved without WildFly channels. "REQUIRED" means that the feature-pack and all its artifacts must be only resolved from WildFly channels. "REQUIRED_FP_ONLY" means that only the feature-pack must be only resolved from WildFly channels. Referenced artifacts can be resolved outside of configured WildFly channels. Default value is: `NOT_REQUIRED`. User property is: `wildfly.feature.pack.require.channel.resolution`. Alias is: `wildfly-channel-resolution-mode`.

3.3.4. Parameter Details

addFeaturePacksAsRequiredManifests
Add any feature-pack dependency as a required manifest in the manifest YAML definition. This parameter has no effect if "generate-channel-manifest" is false.

Type: boolean
Required: No
Default: true
Alias: add-feature-packs-as-required-manifests

buildName
The directory for the built artifact.

Type: java.lang.String
Required: No
User Property: wildfly.user.feature.pack.buildName
Default: ${project.build.directory}

configDir
The feature-pack build configuration file directory

Type: java.io.File
Required: No
User Property: wildfly.user.feature.pack.configDir
Default: ${basedir}
Alias: config-dir

configFile
The feature-pack build configuration file.

Type: java.lang.String
Required: No
User Property: wildfly.user.feature.pack.configFile
Default: wildfly-user-feature-pack-build.xml
Alias: config-file

configStatibilityLevel
The default stability level used at provisioning time to generate configuration. Can’t be used when stability-level is set.

Type: java.lang.String
Required: No
Alias: config-stability-level

deployChannelManifest
(no description)

Type: boolean
Required: No
User Property: wildfly.feature.pack.deploy-channel-manifest
Default: true
Alias: deploy-channel-manifest

fpLocation
The FPL for the generated feature-pack.

Type: java.lang.String
Required: No
Default: ${project.groupId}:${project.artifactId}:${project.version}
Alias: feature-pack-location

generateChannelManifest
Generates a channel manifest YAML definition when the feature-pack is produced. Any dependency from the feature pack is declared as a stream in the channel manifest.

Type: boolean
Required: No
User Property: wildfly.feature.pack.generate-channel-manifest
Default: false
Alias: generate-channel-manifest

minimumStabilityLevel
The minimum stability level of the WildFly processes used to generate feature specs and include packages. Set this if you need to generate feature specs for features with a lower stability level than the default level of the WildFly process being used for feature-spec generation.

Type: java.lang.String
Required: No
Alias: minimum-stability-level

packageStatibilityLevel
The default stability level used at provisioning time when installing packages/JBoss Modules modules. Can’t be used when stability-level is set.

Type: java.lang.String
Required: No
Alias: package-stability-level

releaseName
The name of the release the feature-pack represents which will be stored in the feature-pack’s resources/wildfly/wildfly-tasks.properties as product.release.name property.

Type: java.lang.String
Required: No
Default: ${product.release.name}
Alias: release-name

resourcesDir
Represents the directory containing child directories packages, feature_groups, modules etc. Either an absolute path or a path relative to configDir.

Type: java.lang.String
Required: Yes
User Property: wildfly.user.feature.pack.resourcesDir
Default: src/main/resources
Alias: resources-dir

stabilityLevel
The default stability level used at provisioning time to generate configuration and provision packages. Can’t be used when config-stability-level or package-stability-level is set.

Type: java.lang.String
Required: No
Alias: stability-level

taskProps
Various properties that will be added to feature-pack’s resources/wildfly/wildfly-tasks.properties.
NOTE: values of this parameter will overwrite the corresponding values from task-properties-file parameter, in case it’s also set.

Type: java.util.Map
Required: No
Alias: task-properties

taskPropsFile
Path to a properties file content of which will be added to feature-pack’s resources/wildfly/wildfly-tasks.properties file that is used as the source of properties during file copying tasks with property replacement.

Type: java.io.File
Required: No
Alias: task-properties-file

translateToFpl
By default generated build config dependencies are expressed using GAV, set this parameter to true to generate FPL.

Type: java.lang.Boolean
Required: No
Default: false
Alias: translate-to-fpl

wildflyChannelResolutionMode
Feature-pack WildFly channel resolution mode when WildFly channels are configured in the provisioning tooling used to provision this feature-pack. "NOT_REQUIRED" means that the feature-pack and artifacts can be resolved without WildFly channels. "REQUIRED" means that the feature-pack and all its artifacts must be only resolved from WildFly channels. "REQUIRED_FP_ONLY" means that only the feature-pack must be only resolved from WildFly channels. Referenced artifacts can be resolved outside of configured WildFly channels.

Type: org.wildfly.galleon.plugin.WildFlyChannelResolutionMode
Required: No
User Property: wildfly.feature.pack.require.channel.resolution
Default: NOT_REQUIRED
Alias: wildfly-channel-resolution-mode

3.3.5. Plugin configuration

Dependency on WildFly

The pom.xml of the project that makes use of this plugin must express a dependency on the WildFly feature-pack it is depending upon.

Feature-pack configuration

For typical user feature-packs construct (eg: package JBoss modules and define galleon layers), there is no need to define a feature-pack build configuration file. Everything can be configured from the plugin configuration element inside the pom.xml file.

For more advanced configuration, a file named wildfly-user-feature-pack-build.xml can be defined in the project root dir. This file complies with the wildfly-feature-pack-build.xml file syntax but only supports a subset of it.

The following items can be defined:

Feature Pack Location of the feature-pack.
Dependencies (transitives or directs) on other feature-packs.
Default packages.

For example:

<build xmlns="urn:wildfly:feature-pack-build:3.0" producer="org.foo:my-galleon-pack:1.0.0.Final">
    <dependencies>
        <dependency location="wildfly@maven(org.jboss.universe:community-universe):current#17.0.0.Final">
            <default-configs inherit="false"/>
            <packages inherit="false"/>
        </dependency>
    </dependencies>
    <default-packages>
        <package name="my.package1"/>
    </default-packages>
</build>

3.3.6. Galleon feature-pack content that can be defined with the mojo

JBoss module packages

The directory src/main/resources/modules contains JBoss modules to be turned into feature-pack packages. A package is created per JBoss module. JBoss module dependencies are reflected in the corresponding package dependencies.

A module can contain the binaries it wants to see installed or rely on the 'module.xml template' capability of the mojo. For example, here is an excerpt from a module.xml template:

<?xml version="1.0" encoding="UTF-8"?>
<module name="org.postgresql.jdbc" xmlns="urn:jboss:module:1.8">
    <resources>
        <artifact name="${org.postgresql:postgresql}"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

It looks pretty much like the final module.xml except that the artifact name is an expression which should be replaced with either the complete artifact coordinates in case of a thin distribution, e.g.

<?xml version="1.0" encoding="UTF-8"?>
<module name="org.postgresql.jdbc" xmlns="urn:jboss:module:1.8">
    <resources>
        <artifact name="org.postgresql:postgresql:9.4.1211"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

or the resource-root element in case of a fat distribution, e.g.

<module name="org.postgresql.jdbc" xmlns="urn:jboss:module:1.8">

    <resources>
        <resource-root path="postgresql-9.4.1211.jar"/>
    </resources>

    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>

module.xml template processing is happening at provisioning time and depends on the kind of distribution being provisioned. That is controlled by the plugin option jboss-maven-dist=true|false. true to provision a thin installation, false to provision a fat installation.

If you are packaging JBoss module using the "module.xml template" you must express the dependencies on the actual artifacts you want to see provisioned in the pom.xml file.

It is possible that a module depends on another module which is not found in the current feature-pack. In that case, the feature-pack that contains the package representing the module from the dependency must be declared as the dependency of the current feature-pack in the feature-pack build config file. If the dependency could not be resolved locally (among the modules included in the current feature-pack), the module will be looked up in the dependencies of the current feature-pack (in the order the dependencies are specified in the feature-pack build config file).

In case a module dependency could not be resolved neither locally nor in the feature-pack dependencies, an error will be thrown with the corresponding message.

The package generated for a JBoss module can still be customized by, e.g., adding pm/wildfly/tasks.xml to it in src/main/resources/packages. In this case the package dir in src/main/resources/packages has to include only the content that the generated package is missing. It doesn’t have to include package.xml unless the generated one has to be replaced with a custom one.

Custom, add-ons and layers types of JBoss modules

Custom modules are defined directly under modules directory.
add-ons are defined under modules/system/add-ons/<add-on name> directory.
layers are defined under modules/system/layers/<layer name> directory. You must also define the file layers.conf under modules directory.

Galleon packages

The directory src/main/resources/packages/ contains galleon packages. Packages contain content (other than JBoss modules) you want to see provisioned along with a layer and/or configuration.

Documentation to help you define packages can be found here.

Galleon Layers

You can define your own layers (eg: drivers, datasources, customized subsystem) that can be then assembled with WildFly built-in layers to compose a configuration.

The directory src/main/resources/layers contains the layers definitions.

Layers are defined for a given model of configuration. Configuration model can be one of standalone, host or domain. The layers defined for a given configuration model are located inside a directory named with the configuration model: layers/<config model name>/<layer name>/layer-spec.xml

Example of a layer that defines the configuration for a mysql driver and include the driver package (a JBoss module) named com.mysql.jdbc.

<?xml version="1.0" ?>
<layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="mysql-driver">
    <feature spec="subsystem.datasources">
        <feature spec="subsystem.datasources.jdbc-driver">
            <param name="driver-name" value="mysql"/>
            <param name="jdbc-driver" value="mysql"/>
            <param name="driver-xa-datasource-class-name" value="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"/>
            <param name="driver-module-name" value="com.mysql.jdbc"/>
        </feature>
    </feature>
    <packages>
        <package name="com.mysql.jdbc"/>
    </packages>
</layer-spec>

Documentation to help you define layers can be found here.

Galleon feature-groups

You can define your own feature-groups that can then be re-used when defining configurations.

The directory src/main/resources/feature_groups contains the feature-groups definitions. A feature-group is defined inside the file <feature-group name>.xml

For example:

<?xml version="1.0" encoding="UTF-8"?>
<feature-group-spec name="my-feature-group" xmlns="urn:jboss:galleon:feature-group:1.0">
    <feature-group name="another-feature-group"/>
    <feature spec="interface">
        <param name="interface" value="my-interface"/>
        <param name="inet-address" value="192.168.1.1"/>
    </feature>
</feature-group-spec>

Documentation to help you define feature-groups can be found here.

Galleon default configurations

You can define default configurations to be provisioned by galleon. Default configurations are defined in src/main/resources/configs/<config model>/<config name>/config.xml file. Configuration model can be one of standalone, host or domain.

For example:

<config xmlns="urn:jboss:galleon:config:1.0" name="standalone.xml" model="standalone">
    <layers>
        <include name="cloud-profile"/>
        <include name="my-layer"/>
    </layers>
    <feature-group name="my-feature-group"/>
</config>

Documentation to help you define default configurations can be found here.

3.4. build-feature-pack

3.4.1. wildfly-galleon:build-feature-pack

Full name: org.wildfly.galleon-plugins:wildfly-galleon-maven-plugin:7.0.0.Final:build-feature-pack

3.4.2. Description

This Maven mojo creates a WildFly style feature-pack archive from the provided resources according to the feature-pack build configuration file and attaches it to the current Maven project as an artifact. The content of the future feature-pack archive is first created in the directory called layout under the module’s build directory which is then ZIPped to create the feature-pack artifact.

3.4.3. Attributes

Requires a Maven project to be executed.
Requires dependency resolution of artifacts in scope: compile+runtime.
Binds by default to the lifecycle phase: compile.

Table 5. Required Parameters
Name	Type	Since	Description
`[featureSpecsOutput]`	`File`	`-`	The directory where the generated feature specs are written. Default value is: `${project.build.directory}/resources/features`. Alias is: `feature-specs-output`.
`[moduleTemplatesDir]`	`File`	`-`	Used only for feature spec generation and points to a directory where the module templates from the dependent feature packs are gathered before they are transformed and copied under their default destination `wildflyHome`/modules. Intended mainly for debugging. Default value is: `${project.build.directory}/module-templates`. User property is: `wfgp.moduleTemplatesDir`. Alias is: `module-templates`.
`[resourcesDir]`	`String`	`-`	Represents the directory containing child directories `packages`, `feature_groups`, `modules` etc. Either an absolute path or a path relative to `configDir`. Default value is: `src/main/resources`. User property is: `wildfly.feature.pack.resourcesDir`. Alias is: `resources-dir`.
`[wildflyHome]`	`File`	`-`	Used only for feature spec generation and points to a directory from which the embedded WildFly instance will be started that is used for exporting the meta-model. Intended mainly for debugging. Default value is: `${project.build.directory}/wildfly`. User property is: `wfgp.wildflyHome`. Alias is: `wildfly-home`.

Table 6. Optional Parameters
Name	Type	Since	Description
`[addFeaturePacksAsRequiredManifests]`	`boolean`	`-`	Add any feature-pack dependency as a required manifest in the manifest YAML definition. This parameter has no effect if "generate-channel-manifest" is false. Default value is: `true`. Alias is: `add-feature-packs-as-required-manifests`.
`[buildName]`	`String`	`-`	The directory for the built artifact. Default value is: `${project.build.directory}`. User property is: `wildfly.feature.pack.buildName`.
`[configDir]`	`File`	`-`	The feature-pack build configuration file directory Default value is: `${basedir}`. User property is: `wildfly.feature.pack.configDir`. Alias is: `config-dir`.
`[configFile]`	`String`	`-`	The feature-pack build configuration file. Default value is: `wildfly-feature-pack-build.xml`. User property is: `wildfly.feature.pack.configFile`. Alias is: `config-file`.
`[configStatibilityLevel]`	`String`	`-`	The default stability level used at provisioning time to generate configuration. Can’t be used when `stability-level` is set. Alias is: `config-stability-level`.
`[deployChannelManifest]`	`boolean`	`-`	(no description) Default value is: `true`. User property is: `wildfly.feature.pack.deploy-channel-manifest`. Alias is: `deploy-channel-manifest`.
`[forkEmbedded]`	`boolean`	`-`	Used only for feature spec generation and indicates whether to launch the embedded server to read feature descriptions in a separate process Alias is: `fork-embedded`.
`[fpArtifactId]`	`String`	`-`	The artifactId for the generated feature-pack. Default value is: `${project.artifactId}`. Alias is: `feature-pack-artifact-id`.
`[generateChannelManifest]`	`boolean`	`-`	Generates a channel manifest YAML definition when the feature-pack is produced. Any dependency from the feature pack is declared as a stream in the channel manifest. Default value is: `false`. User property is: `wildfly.feature.pack.generate-channel-manifest`. Alias is: `generate-channel-manifest`.
`[minimumStabilityLevel]`	`String`	`-`	The minimum stability level of the WildFly processes used to generate feature specs and include packages. Set this if you need to generate feature specs for features with a lower stability level than the default level of the WildFly process being used for feature-spec generation. Alias is: `minimum-stability-level`.
`[packageStatibilityLevel]`	`String`	`-`	The default stability level used at provisioning time when installing packages/JBoss Modules modules. Can’t be used when `stability-level` is set. Alias is: `package-stability-level`.
`[releaseName]`	`String`	`-`	The name of the release the feature-pack represents which will be stored in the feature-pack’s `resources/wildfly/wildfly-tasks.properties` as `product.release.name` property. Default value is: `${product.release.name}`. Alias is: `release-name`.
`[stabilityLevel]`	`String`	`-`	The default stability level used at provisioning time to generate configuration and provision packages. Can’t be used when `config-stability-level` or `package-stability-level` is set. Alias is: `stability-level`.
`[taskProps]`	`Map`	`-`	Various properties that will be added to feature-pack’s `resources/wildfly/wildfly-tasks.properties`. NOTE: values of this parameter will overwrite the corresponding values from task-properties-file parameter, in case it’s also set. + Alias is: `task-properties`.
`[taskPropsFile]`	`File`	`-`	Path to a properties file content of which will be added to feature-pack’s `resources/wildfly/wildfly-tasks.properties` file that is used as the source of properties during file copying tasks with property replacement. Alias is: `task-properties-file`.
`[wildflyChannelResolutionMode]`	`WildFlyChannelResolutionMode`	`-`	Feature-pack WildFly channel resolution mode when WildFly channels are configured in the provisioning tooling used to provision this feature-pack. "NOT_REQUIRED" means that the feature-pack and artifacts can be resolved without WildFly channels. "REQUIRED" means that the feature-pack and all its artifacts must be only resolved from WildFly channels. "REQUIRED_FP_ONLY" means that only the feature-pack must be only resolved from WildFly channels. Referenced artifacts can be resolved outside of configured WildFly channels. Default value is: `NOT_REQUIRED`. User property is: `wildfly.feature.pack.require.channel.resolution`. Alias is: `wildfly-channel-resolution-mode`.

3.4.4. Parameter Details

addFeaturePacksAsRequiredManifests
Add any feature-pack dependency as a required manifest in the manifest YAML definition. This parameter has no effect if "generate-channel-manifest" is false.

Type: boolean
Required: No
Default: true
Alias: add-feature-packs-as-required-manifests

buildName
The directory for the built artifact.

Type: java.lang.String
Required: No
User Property: wildfly.feature.pack.buildName
Default: ${project.build.directory}

configDir
The feature-pack build configuration file directory

Type: java.io.File
Required: No
User Property: wildfly.feature.pack.configDir
Default: ${basedir}
Alias: config-dir

configFile
The feature-pack build configuration file.

Type: java.lang.String
Required: No
User Property: wildfly.feature.pack.configFile
Default: wildfly-feature-pack-build.xml
Alias: config-file

configStatibilityLevel
The default stability level used at provisioning time to generate configuration. Can’t be used when stability-level is set.

Type: java.lang.String
Required: No
Alias: config-stability-level

deployChannelManifest
(no description)

Type: boolean
Required: No
User Property: wildfly.feature.pack.deploy-channel-manifest
Default: true
Alias: deploy-channel-manifest

featureSpecsOutput
The directory where the generated feature specs are written.

Type: java.io.File
Required: Yes
Default: ${project.build.directory}/resources/features
Alias: feature-specs-output

forkEmbedded
Used only for feature spec generation and indicates whether to launch the embedded server to read feature descriptions in a separate process

Type: boolean
Required: No
Alias: fork-embedded

fpArtifactId
The artifactId for the generated feature-pack.

Type: java.lang.String
Required: No
Default: ${project.artifactId}
Alias: feature-pack-artifact-id

generateChannelManifest
Generates a channel manifest YAML definition when the feature-pack is produced. Any dependency from the feature pack is declared as a stream in the channel manifest.

Type: boolean
Required: No
User Property: wildfly.feature.pack.generate-channel-manifest
Default: false
Alias: generate-channel-manifest

Type: java.lang.String
Required: No
Alias: minimum-stability-level

moduleTemplatesDir
Used only for feature spec generation and points to a directory where the module templates from the dependent feature packs are gathered before they are transformed and copied under their default destination wildflyHome/modules. Intended mainly for debugging.

Type: java.io.File
Required: Yes
User Property: wfgp.moduleTemplatesDir
Default: ${project.build.directory}/module-templates
Alias: module-templates

packageStatibilityLevel
The default stability level used at provisioning time when installing packages/JBoss Modules modules. Can’t be used when stability-level is set.

Type: java.lang.String
Required: No
Alias: package-stability-level

releaseName
The name of the release the feature-pack represents which will be stored in the feature-pack’s resources/wildfly/wildfly-tasks.properties as product.release.name property.

Type: java.lang.String
Required: No
Default: ${product.release.name}
Alias: release-name

resourcesDir
Represents the directory containing child directories packages, feature_groups, modules etc. Either an absolute path or a path relative to configDir.

Type: java.lang.String
Required: Yes
User Property: wildfly.feature.pack.resourcesDir
Default: src/main/resources
Alias: resources-dir

Type: java.lang.String
Required: No
Alias: stability-level

Type: java.util.Map
Required: No
Alias: task-properties

Type: java.io.File
Required: No
Alias: task-properties-file

Type: org.wildfly.galleon.plugin.WildFlyChannelResolutionMode
Required: No
User Property: wildfly.feature.pack.require.channel.resolution
Default: NOT_REQUIRED
Alias: wildfly-channel-resolution-mode

wildflyHome
Used only for feature spec generation and points to a directory from which the embedded WildFly instance will be started that is used for exporting the meta-model. Intended mainly for debugging.

Type: java.io.File
Required: Yes
User Property: wfgp.wildflyHome
Default: ${project.build.directory}/wildfly
Alias: wildfly-home

3.4.5. Feature-pack packages

The Maven project module which creates a feature-pack may describe its packages and/or provide more data for the packages generated from JBoss modules in the Maven module’s src/main/resources/packages.

Every child directory of src/main/resources/packages represents a package with the directory name being the package name. The content of the package directory is going to be copied to the corresponding package directory in the feature-pack.

The usual package directory structure is:

package_name
|- content/
|- pm/
|  `- wildfly/
|     `- tasks.xml
`- package.xml

In general, the only required child of the package directory is package.xml.

Package content directory includes content that will be copied to the installation root directory when the package is installed.

The tasks XML schema contains the definition of the tasks you can add to the tasks.xml file. This example of tasks.xml file contains the set of tasks one can use in a tasks.xml file.

3.4.6. Generating JBoss module packages

JBoss modules of the distribution are turned into feature-pack packages. A package is created per JBoss module. JBoss module dependencies are reflected in the corresponding package dependencies.

JBoss modules packages don’t have to be manually described in src/main/resources/packages.

Traditionally, WildFly-based builds use module.xml templates to generate the final module.xml files based on the distribution type selected: thin (when the JBoss module artifacts are loaded directly from the Maven repository at runtime) or thick (when the JBoss module artifacts are resolved and copied to the distribution directory at provisioning time).

The Maven module that is building a feature-pack may include src/main/resources/modules/system/layers directory containing module.xml templates. The mojo will read those and generate a package per module.xml.

For example, here is an excerpt from a module.xml template:

<module xmlns="urn:jboss:module:1.8" name="org.jboss.as.jmx">
    <properties>
        <property name="jboss.api" value="private"/>
    </properties>

    <exports>
        <exclude path="org/jboss/as/jmx/logging"/>
    </exports>

    <resources>
        <artifact name="${org.wildfly.core:wildfly-jmx}"/>
    </resources>

    <dependencies>
        <!-- skipped content -->

<module name="org.jboss.as.jmx" xmlns="urn:jboss:module:1.8">
    <properties>
        <property name="jboss.api" value="private"/>
    </properties>

    <exports>
        <exclude path="org/jboss/as/jmx/logging"/>
    </exports>

    <resources>
        <artifact name="org.wildfly.core:wildfly-jmx:5.0.0.Beta3-SNAPSHOT"/>
    </resources>

    <dependencies>
        <!-- skipped content -->

or the resource-root element in case of a thick distribution, e.g.

<module name="org.jboss.as.jmx" xmlns="urn:jboss:module:1.8">
    <properties>
        <property name="jboss.api" value="private"/>
    </properties>

    <exports>
        <exclude path="org/jboss/as/jmx/logging"/>
    </exports>

    <resources>
        <resource-root path="wildfly-jmx-5.0.0.Beta3-SNAPSHOT.jar"/>
    </resources>

    <dependencies>
        <!-- skipped content -->

module.xml template processing is happening at provisioning time and depends on the kind of distribution being provisioned.

In case a module dependency could not be resolved neither locally nor in the feature-pack dependencies, an error will be thrown with the corresponding message.

modules.all package

If a feature-pack includes JBoss modules, in addition to the module packages, the mojo will generate a package called modules.all. This package will not contain any content but will simply depend on all the module packages generated for this feature-pack. This package exists for convenience only to be able to install all the modules from the feature-pack (and its dependencies) by including a single package.

Original WildFly feature-packs include modules.all into the default package list at the moment to follow the legacy approach of building distributions. This is configured in the feature-pack build config file.

3.5. Feature-pack build config file (wildfly-feature-pack-build.xml)

Feature-pack building starts with this file. The file describes the feature-pack in terms of its dependencies on other feature-packs, default packages, configs and other options such as from which artifact groups to extract schemas into the distribution’s docs/schema directory.

If the file includes feature-pack dependencies, those feature-packs must be resolvable as Maven artifacts during the build process. They will be explored to collect the provisioning descriptions (such as feature-pack.xml, etc) of the dependencies.

Normally, most of the content of this file will be copied directly into the final feature-pack.xml generated by the mojo. Here is an example from WildFly Servlet feature-pack build config file

<build xmlns="urn:wildfly:feature-pack-build:3.0" producer="wildfly-servlet@maven(org.jboss.universe:community-universe):current">
    <dependencies>
        <dependency group-id="org.wildfly.core" artifact-id="wildfly-core-galleon-pack">
            <name>org.wildfly.core:wildfly-core-galleon-pack</name>
            <packages inherit="false">
                <exclude name="product.conf"/>
            </packages>
            <default-configs inherit="false"/>
        </dependency>
    </dependencies>
    <default-packages>
        <package name="modules.all"/>
        <package name="docs"/>
    </default-packages>
    <package-schemas>
        <group name="org.jboss.as"/>
        <group name="org.wildfly"/>
        <group name="org.wildfly.core"/>
    </package-schemas>
    <config model="standalone">
        <packages>
            <package name="product.conf" optional="true"/>
            <package name="misc.standalone"/>
        </packages>
    </config>

    <!-- other configs are skipped -->

    <generate-feature-specs>
        <extensions>
            <standalone>
                <extension>org.jboss.as.ee</extension>
                <extension>org.jboss.as.naming</extension>
                <extension>org.jboss.as.security</extension>
                <extension>org.wildfly.extension.undertow</extension>
            </standalone>
            <domain>
                <extension>org.jboss.as.ee</extension>
                <extension>org.jboss.as.naming</extension>
                <extension>org.jboss.as.security</extension>
                <extension>org.wildfly.extension.undertow</extension>
            </domain>
        </extensions>
    </generate-feature-specs>
</build>

All the elements in the above example except for package-schemas and generate-feature-specs are actual feature-pack.xml content that will be copied to the resulting feature-pack.xml as-is.

Extracting schemas

The presence of element package-schemas instructs the mojo to create a package called docs.schema. The package includes no content but a file with Maven artifact groupIds from which XSD schemas should be extracted into the distribution’s docs/schema directory, in case docs.schema package was selected to be installed (it is by default).

Feature specs generation

Feature-pack may or may not include feature specs (XML files describing configuration features). Feature specs are included only if the feature-pack includes one or more subsystems that should be added to the confuration when the feature-pack is installed.

In WildFly feature-packs, feature specs are generated. generate-feature-specs is an element that lists extensions included in the feature-pack for which feature specs should be generated.

feature specs are generated using generate-feature-specs goal of the plugin.

Adding provisioning plugins

Feature-packs that depend on WildFly (or WildFly Core), normally, don’t need to add any provisioning plugins to be usable by Galleon. WildFly Core feature-pack includes the plugins that are used during provisioning for all the feature-packs that (directly or indirectly) depend on it. Here is a snipped from WildFly Core wildfly-feature-pack-build.xml that adds WildFly provisioning plugin JARs:

<build xmlns="urn:wildfly:feature-pack-build:3.0" producer="wildfly-core@maven(org.jboss.universe:community-universe):current">
    <!-- content skipped -->

    <plugins>
        <plugin artifact="org.wildfly.galleon-plugins:wildfly-galleon-plugins"/> (1)
    </plugins>

    <resources>
        <copy artifact="org.wildfly.galleon-plugins:wildfly-config-gen" to="wildfly/wildfly-config-gen.jar"/> (2)
    </resources>

    <!-- content skipped -->
</build>

1	`plugins` element may include multiple `plugin` elements specifying Maven artifact coordinates of the plugin
2	`copy` element under `resources` instructs to copy the specified artifact to the feature-pack `resources` directory

Both artifact coordinates above are missing versions. Although the versions could specified, in this case they will be resolved from the Maven project dependencies at the plugin execution time.

WildFly Galleon Plugins Documentation

1. Introduction

1.1. Maven plugins

1.2. Galleon plugins

1.2.1. Installation Plugin options

2. Building a custom feature-pack example

2.1. Setting up Maven project

2.2. Expressing a dependency on WildFly

2.3. Source structure

2.4. Defining JBoss Modules modules

2.5. Defining packages

2.6. Defining layers

2.6.1. my-undertow-handler layer example

2.6.2. mariadb-driver layer example

2.6.3. mariadb-datasource layer example

2.7. Defining feature groups

2.8. Building your feature-pack

2.9. Making your feature-pack available

2.10. Provisioning your feature-pack

2.10.1. WildFly Bootable JAR Maven plugin

2.10.2. WildFly Maven plugin

3. Maven plugin

3.1. Goals overview

3.2. generate-all-artifacts-list

3.2.1. wildfly-galleon:generate-all-artifacts-list

3.2.2. Description

3.2.3. Attributes

3.2.4. Parameter Details

3.3. build-user-feature-pack

3.3.1. wildfly-galleon:build-user-feature-pack

3.3.2. Description

3.3.3. Attributes

3.3.4. Parameter Details

3.3.5. Plugin configuration

Dependency on WildFly

Feature-pack configuration

3.3.6. Galleon feature-pack content that can be defined with the mojo

JBoss module packages

Custom, add-ons and layers types of JBoss modules

Galleon packages

Galleon Layers

Galleon feature-groups

Galleon default configurations

3.4. build-feature-pack

3.4.1. wildfly-galleon:build-feature-pack

3.4.2. Description

3.4.3. Attributes

3.4.4. Parameter Details

3.4.5. Feature-pack packages

3.4.6. Generating JBoss module packages

modules.all package

3.5. Feature-pack build config file (wildfly-feature-pack-build.xml)

Extracting schemas

Feature specs generation

Adding provisioning plugins

2.6.1. `my-undertow-handler` layer example

2.6.2. `mariadb-driver` layer example

2.6.3. `mariadb-datasource` layer example