Installing and deploying web applications using xml-axis

• Introduction
• Creating Webapps
• Installing Dependencies
• Installing Web Services
• Starting the web server
• Installation testing
• Deploying web services
• Testing

Introduction

This document describes how to install Apache Axis. It assumes you already know how to write and run Java code and not be scare of XML. You should also have an application server or servlet engine and be familiar with operating and deploying to it. If you need an application server, we recommend Jakarta Tomcat. Other servlet engines are supported, provided they are version 2.2 or greater. Note also that Axis client and server requires Java1.3 or later.

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

Step 0: Concepts

Before you can do that, you have to install it and get it working.

Step 1: creating the webapps

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. The rest of this document assumes that the default webapp name, "axis" has been used; rename these references if appropriate.

Step 2: setting up the libraries

In the axis directory, you will find a WEB-INF sub-directory. This directory contains some basic configuration information, but can also be used to contain the dependencies and web services you wish to deploy.

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. We recommend xerces jars from the xml-xerces distribution, though others work. If you omit this stage you may be able to use the default XML parser provided by the web application.

Tomcat 4.x and Java1.4

Step 3: starting the web server

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 command from the command line.

Step 4: Validate the Installation

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

Look for the start page

Validate Axis with happyaxis

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.

Look for some services

Test a SOAP Endpoint

  <?xml version="1.0" encoding="UTF-8" ?> 
  <soapenv:Envelope 
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
      xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <soapenv:Body>
      <getVersionResponse 
          soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <getVersionReturn 
              xsi:type="xsd:string">
              Apache Axis version: 1.0 Built on Nov 04, 2002 (01:30:37 PST)
          </getVersionReturn> 
      </getVersionResponse>
      </soapenv:Body>
  </soapenv:Envelope>

Test a JWS Endpoint

To test the JWS service, we make a request against a built in example, EchoHeaders.jws (look for this in the axis/ directory).

Point your browser at http://localhost:8080/axis/EchoHeaders.jws?method=list .

This should return an XML listing of your application headers, such as

<?xml version="1.0" encoding="UTF-8" ?> 
<soapenv:Envelope 
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <listResponse 
            soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
            <listReturn xsi:type="soapenc:Array" 
                soapenc:arrayType="xsd:string[6]" 
                xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
                <item>accept:image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*</item> 
                <item>accept-language:en-us</item> 
                <item>accept-encoding:gzip, deflate</item> 
                <item>user-agent:Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)</item> 
                <item>host:localhost:8080</item> 
                <item>connection:Keep-Alive</item> 
            </listReturn>
        </listResponse>
    </soapenv:Body>
</soapenv:Envelope>

Step 5: installing new Web Services

So far you have got Axis installed and working, now it is time to add your own Web Service.

The process here boils down to (1) get the classes and libraries of this new service into the axis WAR directory tree, (2) tell the AxisEngine about the new file. The latter is done by submitting an XML deployment descriptor to the service via the Admin web service, which is usually done with the AdminClient program or the <axis-admin> Ant task

In the WEB-INF directory, look for (or create) a "classes" directory (i.e. axis/WEB-INF/classes ). In this directory, copy the compiled Java classes you wish to install, being careful to preserve the directory structure of the Java packages.

If your classes services are already packaged into JAR files, feel free to drop them into the WEB-INF/lib directory instead. Also add any third party libraries you depend on into the same directory.

After adding new classes or libraries to the Axis webapp, you must restart the webapp. This can be done by restarting your application server, or by using a server-specific mechanism to restart a specific webapp.

Note: If your web service uses 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.

Step 6: deploying your own web services

The various classes and JARs you have just set up implement your new Web Service. What remains to be done is to tell Axis how to expose this web service. Axis takes a Web Service Deployment Descriptor, (a WSDD file), that describes in XML what the service is, what methods it exports and other aspects of the SOAP endpoint.

The users guide covers these WSDD files; here we are going to use one from the Axis samples; the stock quote service.

• 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.
• Look in axis/samples/stock for the file deploy.wsdd. This is the deployment descriptor we want to tell Axis about.
• execute the following command from the samples/stock directory:

  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.If you have renamed the web application, something other than "axis" change the URL appropriately.

Step 7: testing

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. If you have renamed the web application, something other than "axis" change the URL appropriately.

Advanced Installation: adding Axis to your own Webapp

The core concepts are

1. Add axis.jar, wsdl.jar, saaj.jar, jaxrpc.jar and the other dependent libraries to your WAR file.
2. Copy all the Axis Servlet declarations and mappings from axis/WEB-INF/web.xml and add them to your own web.xml
3. Build and deploy your webapp.
4. Run the Axis AdminClient against your own webapp, instead of Axis, by changing the URL you invoke it with.

Summary