It's the CLASSPATH, stupid!

I've been tearing my hair out for the past two days struggling with the Apache Axis2 Web Services engine. After having had figured out how to integrate Axis2 with Tomcat (see prior blog), the next step involved writing a client to access the Web Service, then integrating that functionality into a servlet.

First off, follow this tutorial.

Following are my tips for getting it done the easy way. Note, I'm sure server administrators will cringe when they see some of my solutions but I'm only looking to prove out the code. This is a development setup on my home computer. 'nuff said.

1. Create a separate project for your Web App (UI, servlets), each Web Service, and each prototype Client code.
   
2. Getting the Web Service to work is easy: follow steps 1 through 4 of the tutorial.
   
3. When going through step 5 (generating Java code from the WSDL), set the destination directory to your Client project /src directory. Note: the generated package name is "org.apache.ws.axis2". At first I thought this was a bug and it was the single biggest source of my headaches.
   
4. In the client project, make 100% certain you've added every-single-jar in $AXIS_HOME/lib to your project CLASSPATH (Project > Properties > Libraries > Add External JARs...). If the Eclipse auto-compiler stops complaining about your imports, you're good to go.
   
5. Compile your Client project. Note, in the tutorial, you run your test program at this point and it "just works". That's BS because they took a serious shortcut by putting the Client code in the same package as the Stub code. In real applications, you won't have that luxury. Package the resulting classes using "jar cvf MyJar.jar org". You will need to be in the /bin directory of your client project for this to work correctly.
   
6. At this point, you can compile and run your servlet, but you'll get a run-time error. This is because the Tomcat servlet runtime does not have the same CLASSPATH as what you've configured in Eclipse. This is the key point that took me days to discover
   
7. Copy that JAR file to $TOMCAT_HOME/lib (yes, you heard correctly... just do it... it works)
   
8. Copy all JAR files in $AXIS_HOME/lib to $TOMCAT_HOME/lib (sacrilege!). If it makes you feel better, make a copy of the $TOMCAT_HOME/lib directory before making any changes.
   

Instead of steps 7 and 8, you can modify the CLASSPATH of the Tomcat servlet runtime. However, I don't know how to do that and was pretty burnt out of the topic by the time I'd figured out the workaround...

It should "just work" now.