JBoss Modules is quite an interesting project that powers JBoss application server and some other projects in the JBoss ecosystem. However, I was surprised to find out that there isn't much you can find about Modules on the webs. Documentation is...  bad  half-done, not that many tutorials exist, and no good examples of how you could use this awesome library in your project. The best you can find is the description on how to apply JBoss Modules within the application server. (sad panda)

I was looking for the simplest "Hello World" example and couldn't find it. Well, why not create one myself then? 

Downloading JBoss Modules

A surprising fact is that you won't find JBoss Modules in the list of upstream projects at jboss.org. 

The first option is to download the jboss-modules.jar from Bintray or Maven Central. And the second option is to build it from sources. 

Oh, OK, one more option (not the best one) is to download the application server that includes jboss-modules.jar, e.g. WildFly.

Hello World

Ahh, the good old "Hello World" :) The main application class is as follows:

public class Main {
    public static void main(String[] args) {
        new Hello().say();
    }
}

So we have a dependency, the Hello class, that will reside in a different module:

public class Hello {
    public void say() {
        System.out.println("Hello!");
    }
}

So to mimic the modules we first have to compile both classes and assemble corresponding JARs. Plus, a proper directory layout is expected by JBoss Modules to resolve the artifacts.

The main class belongs to the 'app' module, and Hello class belongs to the 'hello' module. Each module requires module.xml descriptor. This part is somewhat documented actually. Also the 'main' directory that you see within each module's directory structure is actually a version (!). 

A version slot identifier is an arbitrary string; thus one can use just about any system they wish for organization.  If not otherwise specified, the version slot identifier defaults to "main".

Here's the module.xml for the app module:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.5" name="app">
    <main-class name="Main"/>

    <resources>
        <resource-root path="main.jar"/>
    </resources>

    <dependencies>
        <module name="hello"/>
    </dependencies>
</module>

It specifies the main class (i.e. Main), the reference to the actual JAR that will be used in this module's classpath, and a dependency - the 'hello' module.

Same module.xml for the 'hello' module:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.5" name="hello">
    <resources>
        <resource-root path="hello.jar"/>
    </resources>
</module>

Voila! Now we can execute our brand new modular "Hello World" app:

java -jar jboss-modules-1.5.1.Final.jar -mp mods app

Hello! 

The format for the command is as follows. First, java -jar jboss-modules.jar is used to bootstrap the environment; -mp mods, and the 'app' parameter is the name of the application module that should be executed.

This example isn't really practical, but at least it gives a hint on how to get started with JBoss Modules. Hopefully, one day, the documentation for this awesome project will be complete and there will be a few more tutorials for different the use cases.