Version 2

    On this page I want to lay out some alternative approaches to altering the AS 7.2 / EAP 6.1 boot to realize the objectives discussed in


    Primary goals:


    1. To support the organization of modules as described on, such that the modules that ship with AS 7.2 comprise the "distribution base" discussed on that document.
    2. To ensure that when other valid "layered distributions" or "add-on"s install on top of that AS 7.2 distribution base they can place their modules in appropriate locations as described in and don't need to alter the startup scripts in order to have those modules become visible with the proper precedence.
    3. To ensure the the $JBOSS_MODULE_PATH environment variable is left available for use by end users and isn't polluted with the various detailed paths discussed on


    Secondary goals:


    These are things to consider while working to achieve the primary goal:


    1. To eliminate as much as possible standard configuration settings from the startup scripts.
    2. To organize any remaining script-based standard configuration settings to make them easily usable by tooling.
    3. To avoid altering the programmatic launch of the AS such that existing tooling that launches the AS will not need to handle AS 7.2 / EAP 6.1 separately from how previous AS 7.1 / EAP 6.0 was handled.


    Some of the secondary goals may prove contradictory.


    Current Boot


    The critical aspects of our existing launch commands can be boiled down to the following for a standalone  server and a managed domain host respectively:


    java -jar jboss-modules.jar -mp modules
    java -jar jboss-modules.jar -mp modules


    (The real command uses $JBOSS_HOME to create absolute paths. That is omitted in this document for brevity.)


    The main() class invoked by the JVM is a JBoss Modules class in jboss-modules.jar. It reads the -mp command line argument to learn that modules are available under filesystem path "modules". It then loads either the or the module, finds the class described as the "main" class in that module's module.xml file, loads it and invokes its main() method.




    The following options for how to do the boot come to mind:


    Include the layering logic within JBoss Modules


    If JBoss Modules natively supported the layering rules, this would be simplest. The AS could simply reorganize its module directory layout and it would just work.


    This is the current plan (Jan 18, 2013). The layering rules and patching mechanism we propose for the AS are a valid general set of behavior that any complex application built on jboss-modules might want to take advantage of, so David will build it in.


    Specialized "Main" Modules


    This one was the initial focus but has proved impractical. It involves having most AS modules no longer loaded by the JBoss Modules "boot module loader"; the boot module loader simply loads 1 module which creates a different ModuleLoader to load everything else. But I count 59 spots in the AS code base where the code is accessing Module.getBootModuleLoader(), most, perhaps all of which would break with this approach.


    This the one that's been focused on recently.


    The and modules remain located as they currently are. They do not get placed in modules/layers/base as is described on the Layered Distributions wiki. As a result, a standard jboss-modules boot module loader can find them.


    The code in those modules, however, changes significantly. Essentially it no longer particular concerns itself with those modules do today. Instead, it's sole concern is to figure out the detailed module path as described on the Layered Distributions wiki. It will figure that out and create a ModuleLoader that follows those rules. Using that ModuleLoader it will then load a *different* module located in modules/layers/base, find its main class, load that class and invoke its main() method. That class will execute the logic found in the current main classes.


    An advantage to this is the existing programmatic launch command is completely unchanged.


    The disadvantage is we leave modules located directly under modules. These modules have to be handled different from other modules, however. You can't override them in a patch via a different module. Instead the patch tool has to treat them as a bunch miscellaneous files (like it treats jboss-modules.jar.) This is mildly annoying because they are a special case for the patch generation and application tools. Also RPMs for layered products will have to account for these modules separately; they can't just create a simple symlink to the EAP RPM's modules/layers/base to pick up all the base modules.


    With this approach there will likely be at least 3 of these specialized modules directly under modules/ --, and a 3rd, e.g, that contains the most of the code. The bulk of the code is common between the other two.


    Single Specialized "Main" Module


    No longer under consideration for the same reason as the previous option.


    This is a variant on the previous approach. The launch command becomes:


    java -jar jboss-modules.jar -mp modules


    The goal here is to reduce the number of specialized "Main" modules to just one -- It reads the next argument in the command (e.g. and uses it to decide what module to invoke.


    This makes things a bit less messy in the modules/ dir but at the cost of changing the launch command.

    Specialized JBoss AS Boot Module Loader


    This is the approach that was being followed on the initial work for the patching feature. The command becomes:


    java -cp jboss-modules.jar:jboss-as-loader.jar -jar jboss-modules.jar -mp modules


    The AS ships a jar "jboss-as-loader.jar" alongside jboss-modules.jar. The launch command places that jar on the classpath. JBoss Modules uses system property "boot.module.loader" to discover the classname of the ModuleLoader implementation it should use. The implementation the AS provides understands all the rules in the Layered Distributions wiki.


    The downsides are an extra file in the root of the AS distribution and a change in the launch command.


    New Main Class


    The AS stops using JBoss Modules as its main class. Instead we create our own main class, which does preliminary setup work and then calls JBoss Modules' main() class.


    The launch command becomes:


    java -cp jboss-modules.jar:jboss-as-boot.jar -jar jboss-as-boot.jar -mp modules


    Again, the downsides are an extra file in the root of the AS distribution and a change in the launch command.


    A positive to this is the new main class can take over some processing that's currently done in the scripts. For example, including org.jboss.byteman in system property jboss.modules.system.pkgs. Also the -P processing requested at could be done without requiring it to be added into jboss-modules itself.

    New Main Class with Shading


    This is the same as the "New Main Class" approach, except we shade jboss-modules.jar into jboss-as-boot.jar in order to eliminate a jar. Launch command becomes:


    java -jar jboss-as-boot.jar -mp modules


    Still a change in launch command though. The only way to get around the change in the launch command would be to call this shaded jar "jboss-modules.jar" which would be very, very ugly.