Skip to end of metadata
Go to start of metadata

Module descriptors

A module descriptor is an XML file which describes the structure, content, dependencies, filtering, and other attributes of a module. This format is highly expressive and is tailored for use by the filesystem-backed module loader to allow the module description to reside alongside its content, rather than inside it. In particular, its location on the filesystem is calculated by converting the dot-separated segments of the module name to path elements, followed by a path element which consists of the version slot for that module. This path is then appended to each module path root in turn until a file named module.xml is found within it.

Below is an example of a module descriptor used by the JBoss Application Server:

Example module descriptor

The root module element

The root element of the module descriptor determines what type of module is being specified. There are two types: a regular module and a module alias.

Regular module descriptors have a root element named "module" from the "urn:jboss:module:1.1" namespace. The "module" element supports the following attributes:

Attribute Type Required? Description
name string Yes The name of the module. This name must match the name of the module being loaded.
slot string No The version slot. If not specified, defaults to "main".

The "module" element may contain any of the following elements:

Element Required? Description
main-class No The main class of this module, if any.
properties No A list of properties to make available on this module.
resources No The resources that make up this module.
dependencies No The dependencies for this module.
exports No The filter expressions to apply to the export filter of the local resources of this module.

The main-class element

A module which is defined with a "main-class" element is said to be executable. In other words, the module name can be listed on the command line, and the standard static main(String[]) method in the named module's "main-class" will be loaded and executed.

The "main-class" element supports the following attributes:

Attribute Type Required? Description
name string Yes The name of the main class.

This element may not contain any nested elements.

Note
The main class need not come from the module's actual resources, nor does it need to be exported. Any public class which is visible to the module - which includes all imported dependencies as well as all resource roots - is a valid main class, as long as it has a method with the signature "public static void main(String[] args)".

The resources element

In order for a module to actually have content, you must define the "resources" element with at least one resource root.

A resource root is a specification of a location where the class loader for a module will look for classes and resources. Each module has zero or more resource roots, though most regular modules will contain exactly one, which refers to the JAR file with the module's content.

It is possible to define resource roots for a module which correspond to JAR files as well as file system directories, just like class paths. File system directory resource roots have the additional property of supporting the specification of native libraries, which cannot be loaded from JAR files.

The "resources" element does not support any attributes; it contains zero or more "resource-root" elements. The "resource-root" element supports the following attributes:

Attribute Type Required? Description
path string Yes The path of this resource root, relative to the location of the module.xml file.
name string No The name of the resource root. If not specified, defaults to the resource root's path.

In addition, the "resource-root" element may contain a nested element:

Element Required? Description
filter No A path filter to apply to this resource root. If not specified, all paths are accepted.

See the section on filter definition for more information about defining filters.

The properties element

The modules API exposes a method which can read property (string key-value pair) values from a module. To specify values for these properties you use the "properties" element which can contain zero or more "property" elements, each supporting the following attributes:

Attribute Type Required? Description
name string Yes The name of the property.
value string No The property value; if not given, the property value defaults to "true".

The dependencies element

A module may express one or more dependencies on other module(s) via the "dependencies" element.

The "dependencies" element does not support any attributes. It contains zero or more nested elements as follows:

Element Required? Description
module No A module name upon which a dependency should be added.
system No A specification for expressing a dependency upon the system or application class path.

Module dependencies

The "module" element supports the following attributes:

Attribute Type Required? Description
name string Yes The name of the module upon which this module depends.
slot string No The version slot of the module upon which this module depends; defaults to "main".
export boolean No Specify whether this dependency is re-exported by default; if not specified, defaults to "false".
services enum No Specify whether this dependency's services* are imported and/or exported. Possible values are "none", "import", or "export"; defaults to "none".
optional boolean No Specify whether this dependency is optional; defaults to "false".

* For an introduction to Java language's service provider interface mechanism, refer : http://download.oracle.com/javase/tutorial/sound/SPI-intro.html

In addition, the "module" element supports the following nested elements:

Element Required? Description
imports No A path filter used to restrict what paths are imported from the dependency.
exports No A path filter used to restrict what imported paths are re-exported from this module.
Example of adding an explicit exclude for a dependency

See the section on filter definition for more information about filters.

System dependencies

The "system" element expresses a dependency which is satisfied by accessing paths and packages from the class loader which loaded JBoss Modules (this is usually the system's application class loader). The element supports the following attributes:

Attribute Type Required? Description
export boolean No Specify whether this dependency is re-exported by default; if not specified, defaults to "false".

It also contains nested elements as follows:

Element Required? Description
paths Yes Specify the list of paths (or packages, with "." transformed to "/") which are exposed by this dependency.
exports No A filter which restricts the list of packages/paths which are re-exported by this module. If not specified, all paths are selected (does not apply if the export attribute on the system element is false or unspecified).

The root module-alias element

A module alias descriptor defines a module which is simply another name for a second module. The root element is called "module-alias" and supports the following attributes:

Attribute Type Required? Description
name string Yes The name of the module. This name must match the name of the module being loaded.
slot string No The version slot. If not specified, defaults to "main".
target-name string Yes The name of the module to which this alias refers.
target-slot string No The version slot of the module to which this alias refers. If not specified, defaults to "main".
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jan 13, 2012

    How about the <system> element?

  2. Apr 21, 2012

    An example would be really helpful for the part when you say:

    "In particular, its location on the filesystem is calculated by converting the dot-separated segments of the module name to path elements, followed by a path element which consists of the version slot for that module. This path is then appended to each module path root in turn until a file named module.xml is found within it."

    I came across this section just looking to solve a business problem of having a jar exposed to all my wars.  A step by step tutorial on how to do so is sorely needed.

  3. Apr 18, 2013

    Can someone please provide an example for the following:

    "It is possible to define resource roots for a module which correspond to JAR files as well as file system directories, just like class paths. File system directory resource roots have the additional property of supporting the specification of native libraries, which cannot be loaded from JAR files."

    Is it possible to use a <resource-root path="/home/me/bin"/> to find/load /home/me/bin/myClass.class at runtime?

    1. Apr 18, 2013

      Yes, using an absolute path to a directory should work exactly the same as if you had put that directory on a class path.

      1. Apr 23, 2013

        David,

              Thanks for the reply.  I never got the absolute paths to work...tried both Windows (well, Cygwin) and RHEL 5.4.  I ended up having to use a nasty relative path <resource-root path="../../../../../home/me/bin"/> to find/load /home/me/bin/myClass.class at runtime.  JBoss7.1.1...hope it helps someone else.  Cheers.

      2. Jun 25, 2013

        I'm not sure if it was intentional but looking at the implementation, it doesn't look like it supports absolute paths for the "path" attribute of a resource-root element https://github.com/jbossas/jboss-modules/blob/master/src/main/java/org/jboss/modules/ModuleXmlParser.java#L133. That line considers the path to be always relative to the "rootPath" which turns out to be the folder containing the module.xml being parsed.

  4. Apr 23, 2013

    OK I'll have to check it out.

  5. Jul 04, 2013

    David,

    Great job! I still have a lot of unanswered questions, though.

    First off, what is the purpose of the module-alias?

    When should it be used? Can you give us an example?

    Any help would be greatly appreciated.

    Thanks in advance!

    1. Jul 08, 2013

      Module aliases are used to allow a module to be loaded by another name. For example in WildFly, the "org.apache.commons.logging" module is actually an alias for "org.slf4j.jcl-over-slf4j".

  6. Sep 04, 2013

    "See the section on filter definition for more information about defining filters." - Where can I find this section?

    1. Feb 25, 2014

      Not completed, unfortunately.

  7. Jan 05, 2014

    How to name the jboss modules xml ? Which directory should the module xml be placed?

    1. Feb 25, 2014

      The static module loader expects the module descriptor to be named "module.xml" and to reside in the directory corresponding to the module based on its name (where dots are replaced with the platform file separator) and slot (which forms the last segment of the directory name).

  8. Feb 19, 2014

    It looks like the <system> <paths> element takes an undocumented "optional" attribute, which is good because I think I need it

    (at least, I don't get a startup error when I do this - I did get errors when I tried <system optional="true"> and <path name="..." optional="true" />)

    1. Feb 19, 2014

      It does not. However I have a bad habit of not making sure that elements with no attributes are really given no attributes - in this case the attribute is simply ignored rather than rejected. I'll comment further on that JIRA.

  9. Nov 07, 2014

    I found no easy way how to make a module, I would like to have a plugin that could  generate the module.xml and all needed jars. I have started to develop a simple gradle plugin that allows to build JBoss Modules. You can define custom module using gradle dependencies and groovy. Also you have an access to modules under JBoss Server.

    https://github.com/zhurlik/gradle-jboss-modules-plugin

  10. Jan 23, 2015

    Under JBoss EAP 6.2, I have a module to access an external file resource, using a relative path like this

    <resource-root path="../../../../../resources, but it doesn't seem to work. How can I tell

    if the module.xml file is being read by JBoss?

    1. Jan 23, 2015

      Assuming you're talking about a module.xml file, whether or not it is read, that won't work because static module resource roots cannot "escape" their module directories. Instead, you could put a symbolic link to your resources directory and add that to the module resource roots list.

  11. Jul 23, 2015

    <properties>
    color: Color value is invalid

     

    <property name="jboss.api" value="private"/>
    color: Color value is invalid

     

    </properties> if i add above tag in module.xml file am getting is using a private module which may be changed or removed in future versions without notice. what does it means ?
    1. Jul 23, 2015

      It doesn't mean anything if you do it. The module properties are just arbitrary key-value pairs. JBoss AS and WildFly look for a "jboss.api" property when deployments depend on a module, to warn you if you're using a module that might get removed from the distribution.

      If you have more questions, please refer to the user forums at https://developer.jboss.org/en/wildfly?view=discussions.

  12. Mar 10, 2016

    My resource-root tag looks like this...

    <resource-root path="#folderName" />where "#folderName" folder contains jars I need to include in the module. However, these jars do not appear accessible to a deployment which has this module as a dependency. Is this syntax not allowed? I know for a fact that this syntax is valid for deployment resources. Is there a problem when I do this for modules?

    1. Mar 10, 2016

      Correct, at present you must list each class path JAR and directory as separate resource roots. Directories of JARs are not recursed.

  13. Mar 15, 2017

    Just note about <exports> section: When booth, <exclude>  and <include>, are used and more of them match package of classloaded file, first (most-top) matching rule is used.

    Also does not depend if the exclusion/inclusion is done using <include-set> or <include> element - only on order in module.xml file.

    And maybe the most importent: filter applies on package - it is not possible to filter individual classes.

    (maybe should be mentioned in this doc)