title: Unable to resolve class loading issue with JBoss EAP 6.2
body: <p><strong>(see update at end.  It defines a workaround, but that workaround raises questions too).</strong></p>
  
  <p>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.</p>
  
  <p>The strategy is load these jars as <strong>modules</strong>, as JBoss recommends. </p>
  
  <p>This is the jboss-deployment-structure.xml file that we are placing in the war file's WEB-INF directory, again as Jboss recommends:</p>
  
  <pre><code>&lt;?xml version="1.0"?&gt;
  &lt;jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
    &lt;deployment&gt;
        &lt;dependencies&gt;
            &lt;module name="com.whatever.ivss" export="TRUE"/&gt;
            &lt;module name="com.whatever.vt.svcauthentication" export="TRUE"/&gt;
        &lt;/dependencies&gt;
    &lt;/deployment&gt;
  &lt;/jboss-deployment-structure&gt;
  </code></pre>
  
  <p>As per jboss, I then deploy these jars and module.xml descriptors into a directory structure under {JBOSS_EAP_HOME} /modules as follows:</p>
  
  <pre><code>$ 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
  </code></pre>
  
  <p>And here are the two module.xml files referred to above:</p>
  
  <p>.../com/whatever/ivss/module.xml:</p>
  
  <pre><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;module xmlns="urn:jboss:module:1.0" name="com.whatever.ivss"&gt;
    &lt;resources&gt;
        &lt;resource-root path="ivsslib-jdk1.5.jar"/&gt;
    &lt;/resources&gt;
    &lt;dependencies&gt;
          &lt;module name="javax.jms.api"/&gt;
          &lt;module name="javax.servlet.api"/&gt;
          &lt;module name="org.apache.log4j"/&gt;
          &lt;module name="system"/&gt;
    &lt;/dependencies&gt;
  &lt;/module&gt;
  </code></pre>
  
  <p>and .../com/whatever/vt/svcauthentication/module.xml:</p>
  
  <pre><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;module xmlns="urn:jboss:module:1.0" name="com.whatever.vt.svcauthentication"&gt;
    &lt;resources&gt;
        &lt;resource-root path="svcauthentication-jdk1.5.jar"/&gt;
    &lt;/resources&gt;
    &lt;dependencies&gt;
          &lt;module name="com.whatever.ivss"/&gt;
          &lt;module name="system"/&gt;
    &lt;/dependencies&gt;
  &lt;/module&gt;
  </code></pre>
  
  <p>As far as I've been able to discern, I've done everything correctly.<br>
  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):</p>
  
  <pre><code>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
  </code></pre>
  
  <p>I must be doing something wrong but I can't figure out what it is.  Why can't JBoss find my modules?</p>
  
  <p><strong>UPDATE:</strong> </p>
  
  <p>I found a possible solution for this or maybe it's just a bandaid.</p>
  
  <p>The first clue was this log entry included above:</p>
  
  <pre><code>Locally loading module com.whatever.ivss:main ...
  </code></pre>
  
  <p>What is that <strong>:main</strong> doing there?  At no point did I ask for my module to be qualified by the term "main".</p>
  
  <p>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:</p>
  
  <pre><code>[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
  </code></pre>
  
  <p>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.</p>
  
  <p>Following this pattern in my modules, the war now loads successfully.</p>
  
  <p>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?</p>