Unable to resolve class loading issue with JBoss EAP 6.2 - jboss7.x

Question

(see update at end. It defines a workaround, but that workaround raises questions too).
We are trying to port an application to JBoss EAP 6.2 from WebLogic. There will be many difficulties along the way, but now I am just trying to port a single war file and I am stubbing my toe on classloading issues. This war depends on two jars that it does not include. In Web Logic, these jars were on the classpath of the server. Whether or not it makes sense to continue with this pattern, the current effort is to do so. But I can't get it to work.
The strategy is load these jars as modules, as JBoss recommends.
This is the jboss-deployment-structure.xml file that we are placing in the war file's WEB-INF directory, again as Jboss recommends:
<?xml version="1.0"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<deployment>
<dependencies>
<module name="com.whatever.ivss" export="TRUE"/>
<module name="com.whatever.vt.svcauthentication" export="TRUE"/>
</dependencies>
</deployment>
</jboss-deployment-structure>
As per jboss, I then deploy these jars and module.xml descriptors into a directory structure under {JBOSS_EAP_HOME} /modules as follows:
$ pwd
/.../jboss-eap-6.2/modules/com/whatever
$ ls -alR
.:
total 16
drwxrwxr-x. 4 wevs wevs 4096 Aug 14 14:58 .
drwxrwxr-x. 4 wevs wevs 4096 Aug 13 14:07 ..
drwxrwxr-x. 2 wevs wevs 4096 Aug 15 09:44 ivss
drwxrwxr-x. 3 wevs wevs 4096 Aug 14 14:58 vt
./ivss:
total 132
drwxrwxr-x. 2 wevs wevs 4096 Aug 15 09:44 .
drwxrwxr-x. 4 wevs wevs 4096 Aug 14 14:58 ..
-rw-r-----. 1 wevs wevs 121414 Aug 13 14:22 ivsslib-jdk1.5.jar
-rw-r-----. 1 wevs wevs 356 Aug 15 09:44 module.xml
./vt:
total 12
drwxrwxr-x. 3 wevs wevs 4096 Aug 14 14:58 .
drwxrwxr-x. 4 wevs wevs 4096 Aug 14 14:58 ..
drwxrwxr-x. 2 wevs wevs 4096 Aug 14 15:02 svcauthentication
./vt/svcauthentication:
total 24
drwxrwxr-x. 2 wevs wevs 4096 Aug 14 15:02 .
drwxrwxr-x. 3 wevs wevs 4096 Aug 14 14:58 ..
-rw-r-----. 1 wevs wevs 306 Aug 14 15:02 module.xml
-rw-r-----. 1 wevs wevs 11524 Aug 13 14:21 svcauthentication-jdk1.5.jar
And here are the two module.xml files referred to above:
.../com/whatever/ivss/module.xml:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.whatever.ivss">
<resources>
<resource-root path="ivsslib-jdk1.5.jar"/>
</resources>
<dependencies>
<module name="javax.jms.api"/>
<module name="javax.servlet.api"/>
<module name="org.apache.log4j"/>
<module name="system"/>
</dependencies>
</module>
and .../com/whatever/vt/svcauthentication/module.xml:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.whatever.vt.svcauthentication">
<resources>
<resource-root path="svcauthentication-jdk1.5.jar"/>
</resources>
<dependencies>
<module name="com.whatever.ivss"/>
<module name="system"/>
</dependencies>
</module>
As far as I've been able to discern, I've done everything correctly.
Yet the class refuses to load, and looking at the jboss log (on trace level) the error seems to be an inability to FIND my module (rather than some downstream class dependency issue):
10:12:07,254 DEBUG [org.jboss.modules] (MSC service thread 1-4) Module deployment.dbAccess.war:main defined by Service Module Loader
10:12:07,254 TRACE [org.jboss.modules] (MSC service thread 1-4) Loaded module deployment.dbAccess.war:main from Service Module Loader
10:12:07,256 TRACE [org.jboss.modules] (MSC service thread 1-4) Locally loading module com.whatever.ivss:main from local module loader #65c404b3 (finder: local modul
e finder #2810b7f7 (roots: .../jboss-eap-6.2/modules,.../jboss-eap-6.2/modules/system/layers/base))
10:12:07,256 TRACE [org.jboss.modules] (MSC service thread 1-4) Module com.whatever.ivss:main not found from local module loader #65c404b3 (finder: local module find
er #2810b7f7 (roots: .../jboss-eap-6.2/modules,.../jboss-eap-6.2/modules/system/layers/base))
...
10:12:07,256 ERROR [org.jboss.msc.service.fail] (MSC service thread 1-4) MSC000001: Failed to start service jboss.module.service."deployment.dbAccess.war".main:
org.jboss.msc.service.StartException in service jboss.module.service."deployment.dbAccess.war".main: JBAS018759: Failed to load module: deployment.dbAccess.war
:main
at org.jboss.as.server.moduleservice.ModuleLoadService.start(ModuleLoadService.java:91) [jboss-as-server-7.3.0.Final-redhat-14.jar:7.3.0.Final-redhat-14
]
at org.jboss.msc.service.ServiceControllerImpl$StartTask.startService(ServiceControllerImpl.java:1811) [jboss-msc-1.0.4.GA-redhat-1.jar:1.0.4.GA-redhat-
1]
at org.jboss.msc.service.ServiceControllerImpl$StartTask.run(ServiceControllerImpl.java:1746) [jboss-msc-1.0.4.GA-redhat-1.jar:1.0.4.GA-redhat-1]
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145) [rt.jar:1.7.0_51]
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615) [rt.jar:1.7.0_51]
at java.lang.Thread.run(Thread.java:744) [rt.jar:1.7.0_51]
Caused by: org.jboss.modules.ModuleNotFoundException: com.whatever.ivss:main
at org.jboss.modules.Module.addPaths(Module.java:1030) [jboss-modules.jar:1.3.0.Final-redhat-2]
at org.jboss.modules.Module.link(Module.java:1386) [jboss-modules.jar:1.3.0.Final-redhat-2]
at org.jboss.modules.Module.relinkIfNecessary(Module.java:1414) [jboss-modules.jar:1.3.0.Final-redhat-2]
at org.jboss.modules.ModuleLoader.loadModule(ModuleLoader.java:242) [jboss-modules.jar:1.3.0.Final-redhat-2]
at org.jboss.as.server.moduleservice.ModuleLoadService.start(ModuleLoadService.java:70) [jboss-as-server-7.3.0.Final-redhat-14.jar:7.3.0.Final-redhat-14
]
... 5 more
I must be doing something wrong but I can't figure out what it is. Why can't JBoss find my modules?
UPDATE:
I found a possible solution for this or maybe it's just a bandaid.
The first clue was this log entry included above:
Locally loading module com.whatever.ivss:main ...
What is that :main doing there? At no point did I ask for my module to be qualified by the term "main".
Looking a little further, I descended the tree of the JBOSS_EAP_HOME/modules/system directory. These are the factory default dependent modules supplied by JBoss. Every module in here has its module.xml and jar files inside a subdirectory called main.
For example:
[wevs#hdcas01 cal10n]$ pwd
.../jboss-eap-6.2/modules/system/layers/base/ch/qos/cal10n
[wevs#hdcas01 cal10n]$ ls -alR
.:
total 12
drwxrwxr-x. 3 wevs wevs 4096 Nov 20 2013 .
drwxrwxr-x. 3 wevs wevs 4096 Nov 20 2013 ..
drwxrwxr-x. 2 wevs wevs 4096 Nov 20 2013 main
./main:
total 44
drwxrwxr-x. 2 wevs wevs 4096 Nov 20 2013 .
drwxrwxr-x. 3 wevs wevs 4096 Nov 20 2013 ..
-rw-rw-r--. 1 wevs wevs 30262 Nov 20 2013 cal10n-api-0.7.3-redhat-2.jar
-rw-rw-r--. 1 wevs wevs 1419 Nov 20 2013 module.xml
In other words, in the system modules that JBoss defines, the module definition and modules themselves are located in the .../{module name}/main directory, not the .../{module name} directory.
Following this pattern in my modules, the war now loads successfully.
However, this still leaves a question? Why is this "main" subdirectory seemingly required? It is not documented in the JBoss docs. Is this just the solution, or is there some other problematic aspect of my deployment that makes it necessary. Or is it a bug?

Answer 1

JBoss Modules requires a module name and a slot. In your module.xml there is an attribute that can be used called slot which defaults to main. Since your module.xml was not in the main directory it couldn't anything.
In other words the general directory format is package/name/slot. Since the default slot is main JBoss Modules looked in com/whatever/ivss/main for the module.xml file.

Answer 2

Further investigation shows this to be a fairly serious documentation error. I have posted this as a bug on the JBoss bugzilla:
https://bugzilla.redhat.com/show_bug.cgi?id=1130642
There are some other jboss documents that contradict the ones I was reading, details are in the bug report.
This cost me close to a day's worth of headscratching.