Monday, October 24, 2011

How to make correct classloading using JBoss AS 5.1

After I have added new functionality to my project I've spent a lot of time trying to make it work with JBoss AS 5.1 . The problem was that JBoss AS 5.1 has some libraries in the package with itself (look $JBOSS_HOME/lib, $JBOSS_HOME/lib/endorsed, $JBOSS_HOME/common/lib) and I wanted to use different version then provided with JBoss. But let's tell about everything consequently.

At first I tried to do nothing specific and have just specified my maven dependencies with compile scope. And of course I got exception:
java.lang.ClassCastException: org.apache.xerces.jaxp.DocumentBuilderFactoryImpl cannot be cast to javax.xml.parsers.DocumentBuilderFactory
    at javax.xml.parsers.DocumentBuilderFactory.newInstance(Unknown Source)
    at org.apache.log4j.xml.DOMConfigurator.doConfigure(
    at org.apache.log4j.xml.DOMConfigurator.doConfigure(
    at org.apache.log4j.helpers.OptionConverter.selectAndConfigure(
    at org.apache.log4j.LogManager.<clinit>(
    ... 82 more

At first I got flabbergasted. What does this exception mean? I don't even use Apache Xerces in my project.
So that means one of libraries I use is dependent on it. Then I tried to write separate mock project for this newly added libraries. And it worked fine. Then it means JBoss is involved with this exception. And of course it is. JBoss had the xercesImpl.jar in $JBOSS_HOME/lib/endorsed.

So here we have version conflict. What can we do in this situation. There are some solutions to this situation:
  1. Remove all conflicting jars from your application (make all conflicting maven dependencies in provided scope). But in my opinion, this is bad idea, because
    • it would make the application dependent on Application Server
    • it may result in a lot of rework on currently good working code 
  2. Change JBoss AS libraries with the correct versions (all conflicting maven dependencies should be in provided scope). But it has another problems:
    • you have to reconfigure your server; if you develop in team then all your teammates have to do the same with their working environment;
    • it may result in LinkageError. In my case it meant that QName class was already loaded by boot Classloader and it means that I cannot use it in my classes(loaded by another Classloader). If you're interested about this error see link1 and link2.
      • java.lang.LinkageError: loader constraint violation: when resolving method
            the class loader (instance of org/jboss/classloader/spi/base/BaseClassLoader) of 
            the current class, some/path/to/my/class, and the class loader 
            (instance of <bootloader>) for resolved class, 
            org/apache/axis2/description/AxisOperation, have different Class objects for 
            the type javax/xml/namespace/QName used in the signature
  3. Configure JBoss AS classloading for the war with jboss-classloading.xml in your war/ear/jar. This is the best solution on my opinion. Because your application would be still Application Server independent(other servers won't pay attention to this additional file) and does not require additional configuration of Application Server.
So let's discuss the third solution. At first you have to create new jboss-classloading.xml in the correct location:
  • If your application is WAR then place it in /WEB-INF/
  • If your application is EAR or JAR then place it in /META-INF/
And put configuration there. Here is the configuration that worked for me:
<classloading xmlns="urn:jboss:classloading:1.0"
The meaning of attributes:
  • name - usually the name of war/ear/jar
  • parent-first (true/false) - the classloader should load at first everything from your war/ear/jar and then from parent(in case of war/jar within ear it would mean ear, otherwise it's JBossAS)
  • domain - classloading domain, if it already exists then you will add your application there
  • top-level-classloader (true/false) - allows you to take part in parent classloading
  • parent-domain - delegates the classloading for the specified domain if the class is not available in the current domain
  • export-all - exposes your classes to other applications
  • import-all (true/false) - import exposes classes from other applications
That's all. In conclusion here is the links that helped me with this error: