On occasion you may find yourself trying to include Java libraries within your custom components that may be more recent than those already available on the server. DOM4J is a good example.
In the case of DOM4J you will more than likely find this message in your log file: “Caused by: java.lang.NoClassDefFoundError: org/dom4j/xpath/DefaultXPath” which basically means that you’re using DOM4J xPath functionality in your component that technical does not exist on the server.
Although the best practice would be to ensure your libraries and components are all using the same library versions you can get yourself out of a tough spot by using the JarJar tools to rename the packages within the class you would like to include in your component and deploy the renamed jar with your component to avoid the conflict.
You will find the tools and instructions here: http://code.google.com/p/jarjar/
In the case of DOM4J I used the following Ant build to rename both the jaxen and dom4j packages:
<?xml version="1.0" encoding="UTF-8"?>
<project name="Jar Jar Links" default="jar">
<taskdef name="jarjar" classname="com.tonicsystems.jarjar.JarJarTask" classpath="lib/jarjar-1.0rc7.jar"/>
<rule pattern="org.dom4j.**" result="org.etech.dom4j.@1"/>
<rule pattern="org.jaxen.**" result="org.etech.jaxen.@1"/>
Once the build has been run, you can return to your component code and change your import statements to reflect the new package names. Also be sure to include the new jar file in your build path.
A big thank you goes out to the Java Guru Venkata for pointing me to this one.