Modules in JBoss 7.2.0.Final

[raylite3]

Hello,

The modules directory tree in jboss-as-7.2.0.Final has changed. The modules that used to be in modules/ are now in modules/system/layers/base.

So in order to create a new module, do I place it in modules/system/layers/base? Any docs or pointers?

[ctomc]

Hi,

you can still put your custom modules directly into modules directory.

You can find more about new layout here https://community.jboss.org/wiki/LayeredDistributionsAndModulePathOrganization

--

tomaz

[lennartj]

Hello there Tomaz (and all others),

While it is true that we still can put custom modules directly into the modules directory, I can't really deduct the recommended approach to doing various things from the article you refer to. (In fact, the article seems more like a reference documentation). I have been unable to find recommendations or examples for a few commonly used tasks, such as adding modules in the different new contexts.

Assume, for instance, that I would like to add a PostgreSQL datasource for JPA usage - implying that I would need to add a module holding the PostgreSQL driver to the new module system. Is the recommended approach, then, that I:

1. Simply copy the driver and the module.xml file into modules/org/postgresql/main, just like in version 7.1.1?
2. Create a new system layer in which I add the driver module; i.e copy the driver and the module.xml file into modules/system/layers/dbsupport/org/postgresql/main? (Or should we consider system layers reserved for use by the JBoss / Wildfly distributions?)
3. Create a new non-system layer, in which I add the driver module; i.e. copy the driver and the module.xml file into modules/connectivity/layers/dbsupport/org/postgresql/main?
4. Create an add-on containing the driver module; i.e copy the driver and the module.xml file into modules/system/add-ons/dbsupport/org/postgresql/main

Presumably, it would be a good thing to keep the custom module org.postgresql separate from the standard distribution modules - so I would instinctively discard approach 1 above. The semantic differences of a new layer versus a new add-on are described in some detail in the article you refer to - but the article also says:

"This is problematic when layered distributions and add-ons wish to install their own modules, since there are no clear rules as to how those modules should be installed or how they relate to one another."

While this sentence seems to imply that the entire layer/add-on structure are concepts, rather than working implementations, the system/layer/base does exist in the 7.2.0.Final release and is obviously working well....

... implying I am still a tad puzzled about how and where I should add my org.postgresql module and if there are any tasks which must be completed to make the JBoss appserver use a module deployed to - say - modules/system/add-ons/dbsupport/org/postgresql/main.

[jaikiran]

Static user defined modules are not layered distributions. So most of that article really can be skipped from that point of view. Static user defined modules should go in the modules/foo/bar folder just like they used to in 7.1.1.Final - that's the recommended way. And when I say user defined modules, the database drivers too come under that category.

[lennartj]

Hello there, and thank you for taking the time to respond.

However, I am searching for something a tad more normative than that static user-defined modules should not be made layered distributions.

(Why not make a set of user-defined modules into an add-on? Why deploy the user-defined modules in the module root, and making use of a different pattern than the system modules?)

I suppose I would like to see/read some recommendations regarding what types of stuff should go as a layer, an add-on and a "no-namespace-module" as defined in 7.1.1.

Do you know of any such recommendations/recommended best practises?

[jaikiran]

I'll request someone who has more knowledge about this to take a look at this thread to answer your questions.

[brian.stansberry]

We recommend end users place their modules directly in the modules directory because that's simplest.

It's valid to treat your modules as an add-on and organize them accordingly. There might be benefits to that once WildFly 8 is out, as the patching tool that will be included in 8 will understand how to patch layers and add-ons, so if you've created your own add-on you will be able to create and apply your own patches for it. That might be helpful in your operational environment.

I don't recommend creating a layer. The reason to create a layer instead of an add-on is if you feel the need to override modules that ship with WildFly with your own version of the same modules. That's usually not a good idea. If you add your own layer you have created your own "Identity" as discussed on https://community.jboss.org/docs/DOC-47927 and are responsible for everything that entails. At a minimum you have to provide a modules/layers.conf file as discussed in that document. Once the patching feature is out in AS 8, any patches that are available for WildFly or EAP, you won't be able to directly use. You'll have to repackage them to adjust their metadata to reference your custom "identity."

[lennartj]

Hello Brian - and thank you for responding to my query.

Let me see if I understand the recommendations correctly enough to synthesize a simple-to-use checklist for WF and JBoss 7.2.X module deployment, excluding any references to patches since they seem decently simple to understand. I will highlight some of my own assumptions with green color - feel free to comment on them if they are incorrectly phrased or meed clarification. Here goes:

Recommendations for WF/JBoss 7.2.x developers wanting to install custom modules into the application server

The recommended way to install custom modules into your application server is to create a custom add-on. Custom add-ons should be placed in a standard module tree structure below directory ${JBOSS_HOME}/modules/[Owner]/add-ons/[Categorization], where [Owner] identifies the owner/publisher of the custom add-on, and [Categorization] describes it. To harmonize with patching tools, the [Owner] part may be created as several directories, but [Categorization] must be a single directory.

The add-on is made available to the WF/JBoss application server by adding a line in the file ${JBOSS_HOME}/bin/product.conf with the following structure: /modules/[Owner]/add-ons/[Categorization], where [Owner] and [Categorization] is defined as per above. The load order of the modules correspond to the order in which they appear in the product.conf file.

Example:

Assume that the organisation "jGuru Europe AB" should create a custom add-on holding modules for database support.

Valid module installation locations:

• ${JBOSS_HOME}/modules/jguru/add-ons/dbsupport
• ${JBOSS_HOME}/modules/jguru/europe/add-ons/dbsupport

Invalid module installation location:

• ${JBOSS_HOME}/modules/jguru/add-ons/db/support

The corresponding entries for the two valid module installation locations above in the product.conf file should be:

• /modules/jguru/add-ons/dbsupport
• /modules/jguru/europe/add-ons/dbsupport

The only exception to this recommendation is when existing modules within the distribution must be replaced/overridden by custom modules, in which case the recommended way is to create a custom layer. This approach should be considered last resort unless you are building application distributions on a regular basis or otherwise know what you are doing. Custom layers should be placed in a standard module tree structure below directory${JBOSS_HOME}/modules/[Owner]/layers/[Categorization], where [Owner] identifies the owner/publisher of the custom layer, and [Categorization] describes it. To harmonize with patching tools, the [Owner] part may be created as several directories, but [Categorization] must be a single directory.

The custom layer is made available to the WF/JBoss application server by adding a line in the file ${JBOSS_HOME}/bin/product.conf with the following structure: /modules/[Owner]/layers/[Categorization], where [Owner] and [Categorization] is defined as per above. The load order of the modules correspond to the order in which they appear in the product.conf file.

Example:

Assume that the organisation "jGuru Europe AB" should create a custom layer holding modules for database support.

Valid module installation locations:

• ${JBOSS_HOME}/modules/jguru/layers/dbsupport
• ${JBOSS_HOME}/modules/jguru/europe/layers/dbsupport

Invalid module installation location:

• ${JBOSS_HOME}/modules/jguru/layers/db/support

The corresponding entries for the two valid module installation locations above in the product.conf file should be:

• /modules/jguru/layers/dbsupport
• /modules/jguru/europe/layers/dbsupport

The practise of copying modules to the ${JBOSS_HOME}/modules directory is functional within WF/JBoss 7.2.x, but discouraged for operational reasons. It is simpler to get an overview of, distribute, add and remove all modules within a custom add-on or layers within the application server since all modules reside properly separated from system-layer modules and other custom add-ons and layers.

The recommended practise above also applies to OSGi bundles, although the bundles should be installed within the ${JBOSS_HOME}/bundles instead.

...

One question here: Drawing the conclusions from OSGi and other start-level-based systems, it is rather important that the startup order of add-ons/layers and their modules is well-defined and simple to understand. Should one, perhaps, recommend to explicitly name the startup order/level of add-ons/layers? For example, by morphing each configuration entry within the product.conf file (or, perhaps, another file residing in the ${JBOSS_HOME}/modules and ${JBOSS_HOME}/bundles directories respectively) to something like

<add-on path="jguru/add-ons/dbsupport" relative-to="jboss.modules.dir" start-order="2" />

<layer path="jguru/europe/layers/dbsupport" relative-to="jboss.modules.dir" start-order="3" />

... and so on...

[lennartj]

So ... am I correct with the assumptions for recommendations above?

If not - what is incorrect?

[lennartj]

Come on, folks... is the recommendation described above correct?

Or is there another description for the recommended approach somewhere?