Bug 1130642 - [Doc Bug Fix] Documentation about module directories appears to be incorrect
Summary: [Doc Bug Fix] Documentation about module directories appears to be incorrect
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: JBoss Enterprise Application Platform 6
Classification: JBoss
Component: Documentation
Version: 6.2.0
Hardware: Unspecified
OS: Unspecified
unspecified
high
Target Milestone: post-GA
: EAP 6.3.0
Assignee: sgilda
QA Contact: Russell Dickenson
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2014-08-15 18:29 UTC by Steve Cohen
Modified: 2014-11-23 23:17 UTC (History)
4 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Build Name: 14874, Administration and Configuration Guide-6.2-1 Build Date: 07-04-2014 15:16:16 Topic ID: 4360-458732 [Specified]
Last Closed: 2014-11-23 23:17:14 UTC
Type: Bug


Attachments (Terms of Use)

Description Steve Cohen 2014-08-15 18:29:23 UTC
Title: Modules

Describe the issue:
This URL 

https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.2/html/Development_Guide/chap-Class_Loading_and_Modules.html#Modules1-1

contains the following information:

"The module name, com.mysql, should match the directory structure for the module."

This does NOT appear to be the case and is in fact quite misleading.

A reading of this text would imply that the module.xml and archive should be loaded in the {JBOSS_EAP_HOME}/modules/com/mysql directory.  If this is done, the module will fail to load.

In fact, the Migration guide, 

https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6/html/Migration_Guide/chap-Migrate_Your_Application.html#sect-Configuration_File_Changes

(section 3.1.3.5) 

says something different:

"Create a module.xml file in the EAP_HOME/modules/myorg-conf/main/ directory containing the following XML:"

Following the migration guide's method seems to work.  Following the Development Guide's method does not.

The correct location for the module.xml file and the archives it refers to i

Suggestions for improvement:

Developer's guide should say somehow that the module definition and module archives should be located in the main/ subdirectory of the directory indicated by the module name.  Incidentally, this pattern can be discerned also by following the pattern of the {JBOSS_EAP_HOME}/modules/system tree, where these predefined modules are also found in a main/ subdirectory.


Additional information:
The same documentation error is also found here:
https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.2/html/Administration_and_Configuration_Guide/chap-Configuring_Modules.html#Modules

These documentation errors persist in the 6.3 documents.

Just so you'll know, it cost me close to a day's effort to chase this down.  This is a serious documentation error.

Comment 6 Martin Simka 2014-09-29 12:43:51 UTC
verified

Revision 6.3.0-45

I agree that "Create a Custom Module" is admin procedure. I don't think that it should be added to Development Guide.


Note You need to log in before you can comment on or make changes to this bug.