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(DOMConfigurator.java:694)
    at org.apache.log4j.xml.DOMConfigurator.doConfigure(DOMConfigurator.java:618)
    at org.apache.log4j.helpers.OptionConverter.selectAndConfigure(OptionConverter.java:470)
    at org.apache.log4j.LogManager.<clinit>(LogManager.java:122)
    ... 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:

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

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
    "org.apache.axis2.description.AxisOperation.setName(Ljavax/xml/namespace/QName;)V"
    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

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"
    name="myApp.war"
    parent-first="false"
    domain="DefaultDomain"
    top-level-classloader="true"
    parent-domain="Ignored"
    export-all="NON_EMPTY"
    import-all="true">
</classloading>

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:

Java Dev Tips

Monday, October 24, 2011