 |
Windows / Web Services using Tomcat, Axis, and XMLBeans
< System Information, Benchmarks, Stress Tests | Working With Windows | Web Services with Axis and XMLBeans Example >
Web Services using Tomcat, Axis, and XMLBeans
Installation and Configuration
Acknowledgements
The basis for this procedure was found in this 2006-02-05 Anil John blog entry. Additional hints for resolving issues running the stock quote sample were found in this 2004-12-14 Jason Bodnar email and this 2003-11-01 Jacob Kjome email. The rest was just trial and error, accompanied by grousing and banging of head on hard objects.
What you need
You need the full installation packages for:
In addition, you will need selected files from several other projects. I have bundled these files into axis_support.zip (2.3Mb). If you prefer to get them directly from their respective projects, here’s the list:
Installation procedure
- Install the Sun JDK. If you wish to conserve disk space, deselect the Demos and Source Code. Note the folder where you install the JDK.
- Create the following environment variable (if you installed JDK into a different folder, then specify that folder instead):
JAVA_HOME=C:\Program Files\Java\jdk1.5.0_11
If you don’t know how to set environment variables in Windows XP, refer to the Microsoft Knowledge Base article 310519 How To Manage Environment Variables in Windows XP.
- Add
%JAVA_HOME%\bin to the end of your existing PATH environment variable.
- Open a Command Prompt (on your Start menu under Programs→Accessories) and enter the command:
javac -version dummy.java
It should report the version number and then complain that it cannot read dummy.java . If something else happens, you have probably not set your environment variables correctly, or there could be something wrong with your JDK installation.
- Reboot your computer. This may be unnecessary, but this is Windows and you never know.
- Install Apache Tomcat. There may be some problems with the 6.x release of Tomcat, so try the suggested 5.5.23 version first --- that is the version that worked for me. Run the Windows Service Installer.
- Change the installation directory to
C:\DevTools\Tomcat5.5 (notice that the space between Tomcat and 5.5 should be removed) and select a FULL installation.
- Unless you have another web server running, change the HTTP Connector Port to
80 (the default is 8080 ).
- Set the administrator userid and password as you wish.
- When asked for the path to the Java JVM, select the folder where you installed the JDK (e.g.
C:\Program Files\Java\jdk1.5.0_11 ), not some JRE folder.
- If you expect to provide web services to remote machines and you have a firewall running on your computer, configure that firewall to let in ports 80/443.
- Create the following environment variable:
CATALINA_HOME=C:\DevTools\Tomcat5.5
- Reboot your computer. This may be unnecessary, but this is Windows and you never know.
- In your favorite browser (which should be Firefox), go to http://localhost/. You should see your Tomcat home page which says:
If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!
- Install Axis.
- Using 7-Zip (or your favorite ZIP program), extract the contents of the
axis-bin-1.4.zip file into the C:\DevTools folder, creating a C:\DevTools\axis-1.4 folder.
- Add the following environment variables:
AXIS_HOME=C:\DevTools\axis-1_4
AXIS_LIB=%AXIS_HOME%\lib
AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery-0.2.jar;
%AXIS_LIB%\commons-logging-1.0.4.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;
%AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\wsdl4j-1.5.1.jar;%AXIS_LIB%\activation.jar;
%AXIS_LIB%\mail.jar;%AXIS_LIB%
AXIS_WEBINF=%AXIS_HOME%\webapps\axis\WEB-INF
- If you will be deploying services which use JNI, make sure the system
%PATH% contains the folder(s) where you will store the native libaries.
- Extract the contents of the axis_support.zip file into your
%AXIS_WEBINF%\lib folder. If you have downloaded the packages individually, copy the following files from each indicated project into that folder:
activation.jar from JAF
mail.jar from JavaMail
xercesImpl.jar and xml-apis.jar from Xerces
xmlsec-1.3.0.jar from XML-Security
wss4j-1.5.1.jar from WSS4J
- Also extract/copy
activation.jar and mail.jar into %AXIS_LIB% (make sure those two jars exist in both folders).
- Register Axis with your Tomcat server by creating a file called
axis.xml in your %CATALINA_HOME%\conf\Catalina\localhost folder, and editing that file (e.g. using WordPad). Make sure it contains only the following line:
<Context docBase="C:\DevTools\axis-1_4\webapps\axis" />
- Reboot your computer. This time there is no maybe; just do it.
- In your favorite browser, go to http://localhost/axis/. You should see the “Welcome to Apache-Axis” page. Click on the Validation link. The “Axis Happiness Page” should report that all components are found. If not, you probably extracted the
axis-support.zip jar files into the wrong folder or otherwise failed to get all six jar files into the correct folder.
- Back on the “Welcome to Apache-Axis” page, click on the Call link. That should display a page of XML that looks similar to:
If you see errors or something completely different from what’s shown above, go back through all the steps in this Install Axis section and make sure you did everything correctly. If it still fails, seek help from the Axis project.
- Deploy a sample web service. Open up a Command Prompt and navigate to your
%AXIS_HOME% folder.
- Axis comes with the samples pre-installed in the
%AXIS_WEBINF%\lib folder. The one we will be using is in the stock folder there.
- For now, however, you need to navigate to the
%AXIS_HOME%\samples\stock folder and issue the command shown in this screen shot:
Note that the "@java -cp …” command is all one line, it will just wrap around in your Command Prompt window. For your convenience, if you would like to simply copy and paste the command, here it is (even if it displays on multiple lines, it will copy as one line):
java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient -lhttp://localhost/axis/services/AdminService deploy.wsdd |
If you get any sort of errors from doing exactly what’s shown, seek help from the Axis project or use your favorite search engine (Google is your friend).
- Test that you can access the “stock” sample web service as shown in this screen shot:
Note that, once again, the “
java -cp …” command is all one line, it will just wrap around in your Command Prompt window. For your convenience, if you would like to simply copy and paste the command, here it is (even if it displays on multiple lines, it will copy as one line):
java -cp .;%AXISCLASSPATH% samples.stock.GetQuote -lhttp://localhost/axis/servlet/AxisServlet -uuser1 -wpass1 XXX |
If you get any sort of errors from doing exactly what’s shown, seek help from the Axis project or use your favorite search engine (Google is your friend).
You are now ready to create and deploy your own applications. There are a number of ways of doing that, see the Other resources section below for websites that might help you be successful at that.
- Install XMLBeans.
- Using 7-Zip (or your favorite ZIP program), extract the contents of the
xmlbeans-2.2.0.zip file into the C:\DevTools folder, creating a C:\DevTools\xmlbeans-2.2.0 folder.
- Add the following environment variable:
XMLBEANS_HOME=C:\DevTools\xmlbeans-2.2.0
XMLBEANS_LIB=%XMLBEANS_HOME%\lib
XMLBEANSCLASSPATH=%XMLBEANS_LIB%\xbean.jar;%XMLBEANS_LIB%\jsr173_1.0_api.jar
- Add
%XMLBEANS_HOME%\bin to your PATH .
- Copy all the jars in
%XMLBEANS_LIB% to %AXIS_WEBINF%\lib .
- Edit
scomp.cmd (in the %XMLBEANS_HOME%\bin folder) using NotePad or WordPad. Change the line which reads
java -classpath "%cp%" org.apache.xmlbeans.impl.tool.SchemaCompiler %*
to
"%JAVA_HOME%\bin\java" -classpath "%cp%" org.apache.xmlbeans.impl.tool.SchemaCompiler %*
If you are going to be working in Cygwin, edit the scomp file, changing the last line to
"$JAVA_HOME/bin/java" -Xmx256m -classpath "$cp" org.apache.xmlbeans.impl.tool.SchemaCompiler "$@"
- To make sure everything is installed OK, run the command
scomp -version in a Command Prompt and check that it does report the version and not some error message.
Error and warning messages avoided
Errors and warnings I encountered along the way when trying to test the stock quote sample, which are avoided if the above procedure is followed, include the following.
- This error is fixed by adding the
wsdl4j jar to the %AXISCLASSPATH% :
Exception in thread "main" java.lang.NoClassDefFoundError Source code of java.lang.NoClassDefFoundError: javax/wsdl/OperationType |
at org.apache.axis.description.OperationDesc Source code of org.apache.axis.description.OperationDesc<clinit>(OperationDesc.java:58) |
at org.apache.axis.client.Call Source code of org.apache.axis.client.Call(Call.java:941) |
at org.apache.axis.client.Call Source code of org.apache.axis.client.Call(Call.java:984) |
at samples.stock.GetQuote Source code of samples.stock.GetQuote(GetQuote.java:70) |
at samples.stock.GetQuote Source code of samples.stock.GetQuote(GetQuote.java:95) |
- Warnings about initializing
log4j are eliminated by adding %AXIS_LIB% to %AXISCLASSPATH% :
log4j:WARN No appenders could be found for logger (org.apache.axis.i18n.ProjectResourceBundle). |
log4j:WARN Please initialize the log4j system properly. |
- Warnings about attachment support being disabled are eliminated by adding
activation.jar and mail.jar to %AXISCLASSPATH% (which is why you also extract/copy them into %AXIS_LIB% in the procedure above):
Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled. |
- If you deploy a service dependent on XMLBeans and either: 1) Axis won’t start, 2) Axis starts but doesn’t list all the services it should, or 3) if it lists all the services but clicking on the
wsdl link for the service dependent on XMLBeans gets you to a page about an Axis fault; you forgot to copy the XMLBeans jars into %AXIS_WEBINF%\lib or you failed to fix the permissions on the copied files (see below).
Other resources
- If you installed Axis as described above, open
C:\DevTools\axis-1_4\docs\index.html in your favorite browser to access the Axis documentation. Or, you can just go to ws.apache.org/axis/java/index.html for the same set of documents.
- The Recommended Reading page on the Axis website has a nice list of Axis-related resources, both on-line and in print.
Web Services Usage -- Tips and Tricks
Much of this may be second-nature to Java programmers; but I am not a Java programmer. I won’t remember this stuff a week from now if I don’t use it again until then.
- Remember to use the
-cp %AXISCLASSPATH% when compiling a client. You don’t need it when compiling a simple service.
- Remember to have the top level directory in the classpath when running a client. For example, to run
samples.userguide.example3.Client , which is located in %AXIS_HOME%\samples\userguide\example3 , the classpath must contain %AXIS_HOME% .
- If you change the code for a service, you must remember to copy the recompiled service
.class file into the appropriate directory tree in %AXIS_HOME%\webapps\axis\WEB-INF\classes . Then you must “Stop” then “Start” axis from the Tomcat /manager .
Breaking File Permissions
If you use Cygwin to deal with any of the files used by Tomcat or Axis, pay special attention that you don’t mess up the alternate access methods? for any of those files. In other words, if the “+” disappears from the permissions of the file (e.g. when you do ls -l ), then things may mysteriously stop working. Hopefully, you have not removed the alternate access methods from all files in the Tomcat or Axis directory tree. Simply find one with the “+” intact and use that getfacl|setfacl trick I mentioned on the referenced page.
Alternately, doing chmod +rx will fix the problem (but may leave the file more accessible to others).
If you deploy a service incorrectly (for example, you have the wrong value for the className property in your WSDD), it may be difficult to undeploy via the AdminService. Simply shut down Axis and edit %AXIS_WEBINF%\server-config.wsdd , removing the entry for your incorrectly deployed service.
For a fairly detailed example web service which uses XMLBeans to support XML-based service request and response, see Web Services with Axis and XMLBeans Example.
< System Information, Benchmarks, Stress Tests | Working With Windows | Web Services with Axis and XMLBeans Example >
|