Getting started with modules on WildFly

A WildFly module is a collection of classes and other resources packaged in a set of JAR files, along with the specification for it. The module specification exposes what the module exports or imports from other modules.

Modules Types

There are two kinds of modules:

  • Statically Deployed Modules. which are available under $JBOSS_HOME/modules directory.
  • Deployment Modules: which are resources deployed into the application server, just like any other application

Installing static modules

Installing a module on WildFly / JBoss EAP requires creating a path under the JBOSS_HOME/modules folder. Under this path, you will install the JAR libraries which are part of the module and a module.xml file which describes the module itself and dependencies with other module.

For example, let’s see how to create a module for the Quartz library:

Create the following path under the JBOSS_HOME:

$ mkdir -p $JBOSS_HOME/modules/org/quartz/main

 Next, include in the main folder the XML descriptor of the module (module.xml) and the JAR files. Here’s a view of your modules structure:

+---org
      +----quartz
                +-----main
                        module.xml
                        quartz-all-2.0.2.jar

Within the module.xml file, you need to declare:

  • The module name
  • The resources which are part of the module (e.g. the list of Jar files)
  • The dependencies from other module which are required.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.quartz">
   <resources>
      <resource-root path="quartz-all-2.0.2.jar" />
   </resources>
   <dependencies>
      <module name="org.slf4j" />
      <module name="javax.api" />
   </dependencies>
</module>

This basically says that the module has a dependency on the other modules: org.slf4j (logging framework) and javax.api module.

To learn how to speed up module creation using the Command Line Interface, check this article: How to install a module on WildFly using the CLI

Besides declaring dependencies, you can also specify some System Properties, so that they are loaded up when the module is available. Here’s an example:

<module xmlns="urn:jboss:module:1.1" name="com.mymodule" >

    <properties>
        <property name="property.name" value="property.value"/>
    </properties>

    <resources>
        <resource-root path="my-module-1.0.jar"/>
    </resources>

</module>

Deployment modules

Deployments in WildFly are also modules. The name of such modules depends on the type of application:

  • Top level modules (e.g. WAR, JAR, RAR ) follow the format deployment.webapp.war
  • EAR modules follow the format deployment.application.ear.webapp.war

It follows that a deployment unit can import classes from another deployment using the other deployments module name. The next section shows how to use a module in an application.

How to use a Module in your application

In order to use this module in your applications you have to trigger a dependency on the module. This can be done by adding into the META-INF/MANIFEST.MF file a Dependency [modulename]

Example:

Dependency: org.quartz			

On the other hand, you can also refer to a deployment module as follows:

Dependency: deployment.webapp.war

Finally, you can also specify the module dependency through the jboss-deployment-structure.xml file:

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

To see more examples about this configuration file, check this article: Examples of jboss-deployment-structure.xml

How to define a global module

It is also possible to set up global modules, that are accessible to all deployments. This is done by modifying the configuration file (standalone/domain.xml).
For example, to add javassist to all deployments you can use the following XML in your standalone.xml/domain.xml

<subsystem xmlns="urn:jboss:domain:ee:1.0" >            
  <global-modules>
    <module name="org.javassist" slot="main" />            
  </global-modules> 
</subsystem>

Note that the slot field is optional and defaults to main. To learn more about module slots, check this article: Configuring module slots in WildFly

Finally, note that since WildFly 19, you can also use global directories in your configuration: Configuring global modules and directories in WildFly

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