Wildfly Extension plugin
Wildfly Extension plugin allows you to install your JBoss Module as an extension with subsystem configuration to WildFly server. This is useful when writing or testing a JBoss subsystem. This plugin takes as input a moduleZip file, that you need to build on your own.
Features
- Install JBoss module as extension to standalone server profile
- Setup subsystem configuration
- Setup socket binding
- Edit and/or replace almost any piece of standalone.xml - this allows to modify other subsystems configurations to ie. setup datasources, caches etc.
Usage
Plugin is currently only available in JBoss Releases repo, to be able to use it in your project, you need to add following into your pom.xml:
<pluginRepositories>
...
<pluginRepository>
<id>jboss-releases</id>
<name>jboss-releases</name>
<url>https://repository.jboss.org/nexus/content/repositories/releases/</url>
</pluginRepository>
...
</pluginRepositories>Requirements
- You need your JBoss module ZIP file ready from previous step of your build. This can be done for example using assemblly plugin. Second way to obtain module.zip is specifying Maven GAV, so the plugin can pull the ZIP from repository.The module is layed down just by unzipping into jbossHome directory. In case directory structure in module does not have server home as it's root, you can set modulesHome configuration option to lay down your module to specified location (i.e modules/system/layers/base in WildFly)
JBoss Module file structure
By default JBoss Module is a ZIP file containing basically module.xml and it's resources (jars etc). In order to simplify plugin configuration, JBoss Module may contain several special files, that plugin is able to detect. It does not matter whether those special files are listed as resources in module.xml or where exactly are they located within the zip file. All these special files can be overriden by plugin configuration.
- subsystem-snippet.xml - sets up subsystem
- socket-binding-snippet.xml - sets up socket-binding
Examples
Install extension to standalone profile
Example configuration to install JBoss module to standalone-full.xml server profile
<profiles>
...
<profile>
<id>install2wf</id>
<build>
<plugins>
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-extension-maven-plugin</artifactId>
<version>0.7.0</version>
<configuration>
<moduleZip>${project.build.directory}/module.zip</moduleZip>
<jbossHome>/jboss/wildfly-8.1.0.Final</jbossHome>
<serverConfig>standalone/configuration/standalone-full.xml</serverConfig>
<subsystem>${basedir}/src/main/resources/standalone-subsystem.xml</subsystem>
</configuration>
<executions>
<execution>
<id>build-dist</id>
<phase>install</phase>
<goals>
<goal>deploy</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
...
</profiles>Install extension from existing module
Example configuration takes JBoss module from Maven repository. This is done by specifying artifact. Note that groupId:artifactId:1.0.0-SNAPSHOT must be also defined among depenencies in your pom.xml.
<profiles>
...
<profile>
<id>install2wf</id>
<build>
<plugins>
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-extension-maven-plugin</artifactId>
<version>0.7.0</version>
<configuration>
<artifact>groupId:artifactId:1.0.0-SNAPSHOT</artifact>
<jbossHome>/jboss/wildfly-8.1.0.Final</jbossHome>
</configuration>
<executions>
<execution>
<id>build-dist</id>
<phase>install</phase>
<goals>
<goal>deploy</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
...
</profiles>Advanced edit operations on standalone.xml
Example configuration only edits standalone.xml and set's up new socket-binding and datasource without installing a module (which includes registering it as JBoss extension) and setting up subsystem.
<profiles>
...
<profile>
<id>install2wf</id>
<build>
<plugins>
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-extension-maven-plugin</artifactId>
<version>0.7.0</version>
<configuration>
<jbossHome>/jboss/wildfly-8.1.0.Final</jbossHome>
<serverConfig>standalone/configuration/standalone.xml</serverConfig>
<edit>
<insert>
<select>/server/socket-binding-group[@name='standard-sockets']</select>
<xml><![CDATA[<socket-binding name="foo" port="12345"/>]]></xml>
<attribute>name</attribute>
</insert>
<insert>
<select>/server/*[namespace-uri()='urn:jboss:domain:datasources:2.0']/*[@local-name()='datasources']</select>
<content>src/main/resources/datasource.xml</content>
<attribute>jndi-name</attribute>
</insert>
</edit>
</configuration>
<executions>
<execution>
<id>build-dist</id>
<phase>install</phase>
<goals>
<goal>deploy</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
....
</profiles>Above example shows how to embed XML content into xml element (first insert). Also note optional attribute element. By specifying it you can make sure your content (in our case socket-binding) get's replaced when we run plugin over and over and at some point you decide to change the port. By default, plugin is able to ensure content identity by taking all attributes and it's values from the root of inserted content - without attribute plugin would internally create an XPath socket-binding[@name='foo' and @port='12345'] to detect if given content should be inserted or updated - if you decide to change the port, this would lead to addition if another socket-binding. With attribute specified it creates socket-binding[@name='foo'], thus socket-binding is always updated.
Second insert puts datasource from separate file. Note that given select must workaround XML namespaces. Again jndi-name attribute is being used to identify our datasource, in this case though it's jndi-name is root attribute name in src/main/resources/datasource.xml file. Also note that subsystem element is only a shortcut to insert putting content to the right place.
For more info about plugin configuration see wildfly-extension:deploy goal.