Examples of jboss-deployment-structure.xml

by

This tutorial contains some examples of how to configure the file jboss-deployment-structure.xml . This file allows to fine tune the modules of your applications running on WildFly. The advantage of using this file (compared to the Manifest’s entry) is that you can define dependencies across top-level deployments and subdeployments.

Basic sample of jboss-deployment-structure.xml

Here is an example which adds a deployed module to the application’s classpath:

<jboss-deployment-structure>
  <deployment>
      <dependencies>
         <module name="deployment.itextpdf-5.4.3.jar" export="TRUE"/>
      </dependencies>
    </deployment>
</jboss-deployment-structure>

Where should you place the jboss-deployment-structure.xml file ?

  • For WAR archives: You can place it in the WEB-INF folder of your archive
  • For JAR/EAR archives: You can place it in the META-INF folder of your archive. See the following picture as an example:

jboss-deployment-structure.xml sample

Next, let’s check a more advanced example. Here we will include the itext dependency just for the sub-module named myapp.war which is included in the EAR:

<jboss-deployment-structure>  
   <sub-deployment name="myapp.war">
    <dependencies>
      <module name="deployment.itextpdf-5.4.3.jar" />
    </dependencies>
  </sub-deployment>  
</jboss-deployment-structure>

The above examples are using deployment-based dependencies; you can however reference your modules installed in the modules folder as in the following example where we are referencing log4j libraries:

<jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="org.apache.log4j" export="TRUE"/>
    </dependencies>
    </deployment>
</jboss-deployment-structure>

To learn mode about WildFly modules, check this article: Getting started with modules on WildFly

Finally, you can also exclude/include some packages from your dependencies. For example, to exclude the com/itextpdf/awt/geom package from the itextpdf-5.4.3.jar which is available as module name “deployment.itextpdf-5.4.3.jar” :

<jboss-deployment-structure>  
   <sub-deployment name="MyWebApp.war">
    <dependencies>
      <module name="deployment.itextpdf-5.4.3.jar" />
    </dependencies>
  </sub-deployment>  
   <module name="deployment.itextpdf-5.4.3.jar" >
    <resources>
     <resource-root path="itextpdf-5.4.3.jar" >
         <filter>
         <exclude path="com/itextpdf/awt/geom" />
       </filter>
     </resource-root>
    </resources>
  </module>  
</jboss-deployment-structure>

How to prevent your modules from being loaded using jboss-deployment-structure.xml

Here’s for example how to prevent your application to use dom4j libraries and use instead the XOM (http://www.xom.nu/) module, available under the name “org.xom”:

<jboss-deployment-structure>
   <deployment>
      <exclusions>
         <module name="org.dom4j" />
      </exclusions>
      <dependencies>
         <module name="org.xom" />
      </dependencies>
   </deployment>
</jboss-deployment-structure>

As a footnote, please be aware that you can use the slot parameter in the module name in order to specify a dependency against a particular release of a module. In the following example we want to replace the default (main) implementation of the com.mysql module with the one contained in the slot named 1.26.

Here’s the view of the com.mysql folder under your modules tree:

~/jboss/wildfly-14.0.0.Final/modules:
└── com
    └── mysql
        ├── 1.26
        │   ├── module.xml
        │   └── mysql-connector-java-5.1.26-bin.jar
        └── main
            ├── module.xml
            └── mysql-connector-java-5.1.31-bin.jar

This is the corresponding configuration needed to use the slot 1.26 for your JDBC Driver:

<jboss-deployment-structure>
   <deployment>
      <exclusions>
         <module name="com.mysql" />
      </exclusions>
      <dependencies>
         <module name="com.mysql" slot="1.26" /> // <1>
      </dependencies>
   </deployment>
</jboss-deployment-structure>

How to prevent a subsystem from being loaded

Another feature of the jboss-deployment-structure.xml file is the ability to prevent the classloader to use a subsystem included in the application server. In the following example, we are excluding the resteasy subsystem that is used for consuming REST Messages:

<jboss-deployment-structure>
   <deployment>
    <exclude-subsystems>
      <subsystem name="resteasy" />
    </exclude-subsystems>
   </deployment>
</jboss-deployment-structure>

You can also combine the exclusion of subsystems with the exclusions of modules. For example, to run Spring on WildFly, you need to exclude both CDI modules and a set of subsystems:

<?xml version="1.0"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <deployment>
        <exclude-subsystems>
            <subsystem name="jsf"/>
            <subsystem name="microprofile-opentracing-smallrye"/>
            <subsystem name="weld"/>
        </exclude-subsystems>
        <exclusions>
            <module name="org.jboss.resteasy.resteasy-cdi"/>
        </exclusions>
    </deployment>
</jboss-deployment-structure>

Finally, please note that if you specify the exclude-subsystem for the top-level archive, it will be inherited by sub deployments, unless the sub deployments specify their own (possibly empty) list.

Found the article helpful? if so please follow us on Socials