Configuring global modules and directories in WildFly

WildFly lets you share a single module across all your Enterprise Applications. This means that it can be added automatically to your application stack, with no deployment configuration. There are two ways to achieve it: Using global directories, which is a new feature introduced in WildFly 19, and using global modules. Let’s see both options.

Configuring Global directories for your modules

WildFly 19 has the ability to define global directories for your modules. This can be an handy solution if the name of a shared library changes very often or if there are many libraries you want to share. This can be done through the ‘ee’ subsystem which allows the configuration of a global directory that will be scanned to automatically include .jar files and resources as a single additional dependency. This module dependency is added as a system dependency on each deployed application.

You can configure a global directory using the following command:

/subsystem=ee/global-directory=my-common-libs:add(path=lib, relative-to=jboss.home.dir)

In the above example, we are using a relative path to point to the global directory. You can also use an absolute path:


When a global-directory is created, WildFly defines a module which has a Jar Resource loader for each jar file included in this directory and its subdirectories.

For example, suppose you have configured one global directory pointing to the following directory tree:


The JBoss Modules module generated after scanning this global-directory will be equivalent to the following module.xml:

<module xmlns="urn:jboss:module:1.5" name="">
        <resource-root path="/home/jboss/tools/libs/commons-math3-3.6.1.jar"/>
        <resource-root path="/home/jboss/tools/libs/poi-4.1.1.jar"/>

        <module name="javaee.api"/>

If you have included files in your global directory, they can be loaded as well by your applications using the context ClassLoader of your current thread:


WARNING: The module created from the shared directory is loaded as soon as the first application is deployed in the server after creating the global-directory. That means, if the server is started/restarted and there are no applications deployed, then the global directory is neither scanned nor the module loaded. Any change in any of the contents of the global-directory will require a server reload to make them available to the deployed applications.

Configuring Global modules

The other option, available also for older WildFly release, is to use Global modules. A Global module is a set of WildFly Modules that will be added as dependencies of every Java EE application deployed on WildFly. Such dependencies allows Java EE deployments to see the classes exported by the global modules.

Each global module is defined through the module resource. For example, to add javassist to all deployments you can use the following XML:

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

The only mandatory attribute is the module name, the slot attribute defaults to main, and both define the JBoss Module ID to reference.

The optional annotations attribute, which defaults to false, indicates if a pre-computed annotation index should be imported from META-INF/jandex.idx

The optional services attribute indicates if any services exposed in META-INF/services should be made available to the deployments class loader, and defaults to false.

The optional meta-inf attribute, which defaults to true, indicates if the Module’s META-INF path should be available to the deployment’s class loader.

Global Modules vs Global directories

Using the Modules directory has the advantage to make more flexible your configuration: if your module’s jar file are updated, for example, it’s not needed to update the module.xml as this is done under the hoods by the application server. This makes this option ideal for development and testing.

Using Global directory, on the other hand, has the advantage of not including any file system link (hard or symbolic) to the Classloading process. This makes this option ideal for production environment.