This document describes how to install xml-axis in as unobtrusive of a manner as possible.  There will be no editing of configuration files, setting of server classpaths, or the like.  Instead, these instructions will rely only on the automatic configuration and isolation that every implementation compliant with the servlet 2.2 specification is required to support.

For more details on using Axis, please see the user's guide.

In your servlet installation, you should find a directory into which web applications (webapps) are to be placed.  Into this directory copy the webapps/axis directory from the xml-axis distribution.  You can actually name this directory anything you want, just be aware that the name you choose will form the basis for the URL by which clients will access your service.

In the directory you just created, you will find a WEB-INF directory.  This contains some basic configuration information, but can also be used to contain the dependencies and web services you wish to deploy.  This is actually the recommended way to deploy as the servlet engine will then keep each web application isolated from each other.

In the WEB-INF directory, you'll find a "lib" directory. 

• In this directory, copy the jars associated with the JAXP 1.1 XML compliant parser of your choice. This generally means either the xerces.jar from the xml-xerces distribution, or the crimson.jar and jaxp.jar from the JAXP 1.1 reference implementation.

Note: Note that there is no requirement that each webapp or the web server itself use the same xml parsers.

If you got this far, the next step should be simple:

In the WEB-INF directory, look for (or create) a "classes" directory. 

• In this directory, copy the services you wish to install, being careful to preserve the directory structure.

Again, isolation is preserved.  And, by the way, should your services already be packaged into jar files, feel free to drop them into the lib directory instead!

Note: If your web service will be making use of the simple authorization handlers provided with xml-axis (this is actually not recommended as these are merely illustrations of how to write a handler than intended for production use), then you will need to copy the corresponding perms.lst and users.lst files into the WEB-INF directory.

This varies on a product by product basis.  In many cases it it as simple as double clicking on a startup icon or running a simple command from the command line.

After installing the web application and dependencies, you should make sure that the server is running the web application.

• Navigate to the start page of the webapp, usually http://127.0.0.1:8080/axis/, though of course the port may differ.
  You should see an Apache-Axis start page.
• Follow the link Validate the local installation's configuration
  This will bring you to a test page that verifies that needed and optional libraries are present. If any of the needed libraries are missing, Axis will not work. You must not proceed until all needed libraries can be found, and this validation page is happy.
  Optional components are optional; install them as your need arises.
• From the start page, select View the list of deployed Web services. This will list all registered Web Services, unless the servlet is configured not to do so. On this page, You should be able to click on (wsdl) for each deployed Web service to make sure that your web service is up and running.

The various classes and jars you have just set up contain a number of interfaces.  What remains to be done is to tell the soap and axis servlets how these are to be combined and what is to be exposed.  There are a number of ways to do this, for now I'll simply describe one way that is suitable for automation.

• Add axis.jar, commons-discovery.jar, commons-logging.jar, jaxrpc.jar, saaj.jar, log4j-1.2.4.jar (or whatever is appropriate for your chosen logging implementation), and the XML parser jar file or files (e.g., xerces.jar) to your classpath.  Locate the deployment descriptor for your service and execute the following command:

  java org.apache.axis.client.AdminClient -lhttp://localhost:8080/axis/services/AdminService deploy.wsdd

Note: You may need to replace localhost with your host name, and 8080 with the port number used by your web server.

This step is optional, but highly recommended.  For illustrative purposes, it is presumed that you have installed and deployed the stockquote demo.

• Add axis.jar, commons-discovery.jar, commons-logging.jar, jaxrpc.jar, saaj.jar, log4j-1.2.4.jar (or whatever is appropriate for your chosen logging implementation), and the XML parser jar file or files (e.g., xerces.jar), as well as the axis installation directory to your classpath.  Change directory to the distribution directory for xml-axis and execute the following command:

  java samples.stock.GetQuote -lhttp://localhost:8080/axis/servlet/AxisServlet -uuser1 -wpass1 XXX

• You should get back "55.25" as a result.

Note: Again, you may need to replace localhost with your host name, and 8080 with the port number used by your web server.