You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by di...@apache.org on 2003/07/23 14:04:11 UTC
cvs commit: xml-axis/java/docs install.html
dims 2003/07/23 05:04:11
Modified: java/docs install.html
Log:
Bug 19435 - awkward documentation for novices (clarification herein)
Bug 21755 - Umbrella bug for Install guide fixes.
Bug 21756 - Include more UNIX examples in install guide
Fix from afindlay@austin.rr.com (Adhamh Findlay)
Revision Changes Path
1.36 +518 -752 xml-axis/java/docs/install.html
Index: install.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/install.html,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -r1.35 -r1.36
--- install.html 27 Jun 2003 14:54:00 -0000 1.35
+++ install.html 23 Jul 2003 12:04:10 -0000 1.36
@@ -1,759 +1,525 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <title>Axis installation instructions</title>
- <link href="axis.css" rel=stylesheet type=text/css>
- </head>
-
- <body>
-<table cellspacing=0 width=100% border=0>
-<tr>
-<td colspan=2>
-<a href="http://ws.apache.org/axis">
-<img border=0 align=left src="images/axis.jpg" />
-</a>
-<h1>
-Installing and deploying web applications using xml-axis
-</h1>
-</td>
-</tr>
+<head>
+ <title>Axis installation instructions</title>
+ <link href="axis.css" rel="stylesheet" type="text/css">
+</head>
+<body>
+<table cellspacing="0" width="100%" border="0">
+ <tbody>
+ <tr>
+ <td colspan="2"> <a href="http://ws.apache.org/axis"><img
+ border="0" align="left" src="images/axis.jpg"> </a>
+ <h1>Installing and deploying web applications using xml-axis </h1>
+ </td>
+ </tr>
+ </tbody>
</table>
-
-<hr size=1 noshade= />
-<strong>
-Contents
+<hr size="1" noshade="noshade">
+<strong>Contents
</strong>
<ul>
-<li>
-<a href="#intro">Introduction</a>
-</li>
-<li>
-<a href="#webapp">Creating Webapps</a>
-</li>
-<li>
-<a href="#depend">Installing Dependencies</a>
-</li>
-<li>
-<a href="#websvc">Installing Web Services</a>
-</li>
-<li>
-<a href="#start">Starting the web server</a>
-</li>
-<li>
-<a href="#install-test">Installation testing</a>
-</li>
-<li>
-<a href="#deploy">Deploying web services</a>
-</li>
-<li>
-<a href="#test">Testing</a>
-</li>
-<li>
- <a href="#advanced">Advanced Installation</a>
-</li>
-<li>
- <a href="#broken">What if it doesn't work?</a>
-</li>
-<li>
- <a href="#summary">Summary</a>
-</li>
+ <li> <a href="#intro">Introduction</a> </li>
+ <li> <a href="#webapp">Creating Webapps</a> </li>
+ <li> <a href="#depend">Installing Dependencies</a> </li>
+ <li> <a href="#websvc">Installing Web Services</a> </li>
+ <li> <a href="#start">Starting the web server</a> </li>
+ <li> <a href="#install-test">Installation testing</a> </li>
+ <li> <a href="#deploy">Deploying web services</a> </li>
+ <li> <a href="#test">Testing</a> </li>
+ <li> <a href="#advanced">Advanced Installation</a> </li>
+ <li> <a href="#broken">What if it doesn't work?</a> </li>
+ <li> <a href="#summary">Summary</a> </li>
</ul>
-
- <a name="intro"/></a>
- <h2>Introduction</h2>
-
- <p>This document describes how to install Apache Axis. It assumes
- you already know how to write and run Java code and are not afraid
- 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 <a
- href="http://jakarta.apache.org/tomcat/">Jakarta Tomcat</a>. [If
- you are installing Tomcat, get the latest 4.1.x version, and the
- full distribution, not the LE version for Java 1.4, as that omits
- the Xerces XML parser]. Other servlet engines are supported,
- provided they implement version 2.2 or greater of the servlet API.
- Note also that Axis client and server requires Java 1.3 or later.
-
- <p>For more details on using Axis, please see the
- <a href="user-guide.html">user guide</a>.
-
- <h2>Things you have to know</h2>
-
- A lot of problems with Axis are encountered by people who are new
- to Java, server-side Java and SOAP. While you can learn about SOAP
- as you go along, writing Axis clients and servers is not the right
- time to be learning foundational Java concepts, such as what an
- array is, or basic application server concepts such as how servlets
- work, and the basics of the HTTP protocol.
- <p>
- Things you need to know before writing a Web Service:
- <ol>
-
- <li> Core Java datatypes, classes and programming concepts.
-
- <li> What threads are, race conditions, thread safety and
- sychronization.
-
- <li> What a classloader is, what hierarchical classloaders are,
- and the common causes of a "ClassNotFoundException".
-
- <li> How to diagnose trouble from exception traces, what a
- NullPointerException (NPE) and other common exceptions are, and how
- to fix them.
-
- <li> What a web application is; what a servlet is, where classes,
- libraries and data go in a web application.
-
- <li> How to start your application server and deploy a web
- application on it.
-
- <li> What a network is, the core concepts of the IP protocol suite
- and the sockets API. Specifically, what is TCP/IP.
-
- <li> What HTTP is. The core protocol and error codes, HTTP headers and
- perhaps the details of basic authentication.
-
- <li> What XML is. Not necessarily how to parse it or anything, just what
- constitutes well-formed and valid XML.
-
- </ol>
-
- Axis and SOAP depends on all these details. If you don't know them,
- Axis (or anyone else's Web Service middleware) is a dangerous place
- to learn. Sooner or later you will be forced to discover these
- details, and there are easier places to learn than Axis.
-
- <p>
-
- If you are completely new to Java, we recommend you start off with
- things like the Java Tutorials on Sun's web site, and perhaps a
- classic book like <a
- href="http://www.mindview.net/Books/TIJ/">Thinking in Java</a>,
- until you have enough of a foundation to be able to work with
- Axis. It is also useful to have written a simple web application,
- as this will give you some knowledge of how HTTP works, and how
- Java application servers integrate with HTTP.
-
- <p>
-
- Be aware that there is a lot more needed to be learned in order to
- use Axis and SOAP effectively than the listing above. The other
- big area is "how to write internet scale distributed applications".
- Nobody knows how to do that properly yet, so that you have to learn this by doing.
-
- <h2>Step 0: Concepts</h2>
-
- Apache Axis is an Open Source SOAP server and client. SOAP is a
- mechanism for inter-application communication between systems
- written in arbitrary languages, across the Internet. SOAP usually
- exchanges messages over HTTP: the client POSTs a SOAP request, and
- receives either an HTTP success code and a SOAP response or an HTTP error code.
- Open Source means that you get the source, but that
- there is no formal support organisation to help you when things go
- wrong.
-
- <p>
-
- SOAP messages are XML messages. These messages exchange structured
- information between SOAP systems. Messages consist of one or more
- SOAP elements inside an envelope, Headers and the SOAP Body.
- SOAP has two syntaxes for describing the data in these elements,
- <i>Section 5</i>, which is a clear descendant of the XML RPC
- system, and <i>XML Schema</i>, which is the newer (and usually
- better) system. Axis handles the magic of converting Java objects
- to SOAP data when it sends it over the wire or receives results.
- SOAP Faults are sent by the server when something goes wrong;
- Axis converts these to Java exceptions.
-
- <p>
-
- SOAP is intended to link disparate systems. It is not a mechanism
- to tightly bind Java programs written by the same team together. It
- can bind Java programs together, but not as tightly as RMI or
- Corba. If you try sending many Java objects that RMI would happily
- serialize, you will be disappointed at how badly Axis fails. This
- is by design: if Axis copied RMI and serialized Java objects to
- byte streams, you would be stuck to a particular version of Java
- everywhere.
-
- <p>
-
- Axis implements the JAX-RPC API, one of the standard ways to program
- Java services. If you look at the specification and tutorials on
- Sun's web site, you will understand the API. If you code to the
- API, your programs will work with other implementations of the API,
- such as those by Sun and BEA. Axis also provides extension
- features that in many ways extends the JAX-RPC API. You can use
- these to write better programs, but these will only work with the Axis
- implementation. But since Axis is free and you get the source, that
- should not matter.
-
- <p>
-
- Axis is compiled in the JAR file <i>axis.jar</i>; it implements
- the JAX-RPC API declared in the JAR files <i>jaxrpc.jar</i> and
- <i>saaj.jar</i>. It needs various helper libraries, for logging,
- WSDL processing and introspection. All these files can be packaged
- into a web application, <i>axis.war</i>, that can be dropped into a
- servlet container. Axis ships with some sample SOAP services. You
- can add your own by adding new compiled classes to the Axis webapp
- and registering them.
- </p>
-
- <p>
- Before you can do that, you have to install it and get it working.
- </p>
-
- <a name="webapp"/></a>
-
- <h2>Step 1: Preparing the webapp</h2>
-
- <p>
- Here we assume that you have a web server up and running on the
- localhost at port 8080. If your server is on a different port,
- replace references to 8080 to your own port number.
-
- </p>
-
- <p>In your Application Server 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.
-
- <a name="depend"/></a>
- <h2>Step 2: Setting up the libraries</h2>
-
- <p>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.</p>
-
- <p>
- Axis needs to have an XML parser in its classpath. If your
- application server or Java runtime does not make one visible to web applications,
- you need to download and add it. Java 1.4 includes the Crimson
- parser, so you <i>can</i> omit this stage, though the Axis team
- prefer Xerces.
-
- <p>
-
- To add an XML parser, acquire the JAXP 1.1 XML compliant parser of
- your choice. We recommend Xerces jars from the <a
- href="http://xml.apache.org/dist/xerces-j/">xml-xerces
- distribution</a>, though others mostly work. Unless your JRE or app
- server has its own specific requirements, you can add the parser's
- libraries to axis/WEB-INF/lib.
-
-
- <h3>Tomcat 4.x and Java 1.4</h3>
- Java 1.4 changed the rules as to to how packages beginning in java.* and
- javax.* get loaded. Specifically, they only get loaded from
- <i>endorsed</i> directories. jaxrpc.jar and saaj.jar contain javax
- packages, so they may not get picked up. If happyaxis.jsp
- (see below) cannot find the relevant packages, copy them
- from axis/WEB-INF/lib to CATALINA_HOME/common/lib and restart Tomcat.
-
- <a name="start"/></a>
- <h2>Step 3: starting the web server</h2>
-
- <p>This varies on a product-by-product basis. In many cases it is as
- simple as double clicking on a startup icon or running a command from
- the command line.</p>
-
- <a name="install-test"/></a>
- <h2>Step 4: Validate the Installation</h2>
-
- <p>
- After installing the web application and dependencies, you should
- make sure that the server is running the web application.
- <h3> Look for the start page </h3>
- Navigate to the start page of the webapp, usually
- <a href="http://127.0.0.1:8080/axis/">http://127.0.0.1:8080/axis/</a>,
- though of course the port may differ.<br>
- You should now see an Apache-Axis start page. If you do not, then
- the webapp is not actually installed, or the appserver is not running.
-
- <h3>Validate Axis with happyaxis</h3>
- Follow the link <i>
- Validate the local installation's configuration</i><br>
-
- This will bring you to <i>happyaxis.jsp</i> a test page that
- verifies that needed and optional libraries are present. The URL
- for this will be something like
-
- <A
- href="http://localhost:8080/axis/happyaxis.jsp">
- http://localhost:8080/axis/happyaxis.jsp</A>
-
- <p>
- If any of the needed libraries are missing, Axis will not work.
- <br><b>You must not proceed until all needed libraries can be
- found, and this validation page is happy.</b> <br> Optional
- components are optional; install them as your need arises. If you
- see nothing but an internal server error and an exception trace,
- then you probably have multiple XML parsers on the classpath, and
- this is causing version confusion. Eliminate the extra parsers,
- restart the app server and try again.
- </p>
-
- <h3>Look for some services</h3>
-
- <p>
-
- From the start page, select <i>View the list of deployed Web services</i>.
- 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 <i>(wsdl)</i> for
- each deployed Web service to make sure that your web service is up and running.
-
- </p>
- <p>
- Note that the 'instant' JWS Web Services that Axis supports are
- not listed in this listing -so when you get to these services, as
- the user guide will, do not panic when the services are not
- listed.
- </p>
-
- <h3>Test a SOAP Endpoint</h3>
-
- Now it's time to test a service. Although SOAP 1.1 uses HTTP POST
- to submit an XML request to the <i>endpoint</i>, Axis also
- supports a crude HTTP GET access mechanism, which is useful for
- testing. First let's retrieve the version of Axis from the version
- endpoint, calling the <code>getVersion</code> method:
-
- <a
- href="http://localhost:8080/axis/services/Version?method=getVersion">
- http://localhost:8080/axis/services/Version?method=getVersion
- </a>
- This should return something like
-<pre class="xml">
- <?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.1 Built on Apr 04, 2003 (01:30:37 PST)
- </getVersionReturn>
- </getVersionResponse>
- </soapenv:Body>
- </soapenv:Envelope>
-</pre>
- The Axis version and build date may of course be different.
-
- <h3>Test a JWS Endpoint</h3>
-
- Now let's test a JWS web service. Axis' JWS Web Services are java files
- you save into the Axis webapp <i>anywhere but the WEB-INF tree</i>,
- giving them the .jws extension. When someone requests the .jws file by
- giving its URL, it is compiled and executed. The user guide covers
- JWS pages in detail.
-
- <p>
-
- To test the JWS service, we make a request against a built-in
- example, EchoHeaders.jws (look for this in the axis/ directory).
- <p>
- Point your browser at
- <a href="http://localhost:8080/axis/EchoHeaders.jws?method=list">
- http://localhost:8080/axis/EchoHeaders.jws?method=list
- </a>.<p>
- This should return an XML listing of your application headers,
- such as
-<pre class="xml"><?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>
-
-</pre>
+<a name="intro"></a>
+<h2>Introduction</h2>
+<p>This document describes how to install Apache Axis. It assumes you
+already know how to write and run Java code and are not afraid 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 <a href="http://jakarta.apache.org/tomcat/">Jakarta
+Tomcat</a>. [If you are installing Tomcat, get the latest 4.1.x
+version, and the full distribution, not the LE version for Java 1.4, as
+that omits the Xerces XML parser]. Other servlet engines are supported,
+provided they implement version 2.2 or greater of the servlet API. Note
+also that Axis client and server requires Java 1.3 or later. </p>
+<p>For more details on using Axis, please see the <a
+ href="user-guide.html">user guide</a>. </p>
+<h2>Things you have to know</h2>
+A lot of problems with Axis are encountered by people who are new to
+Java, server-side Java and SOAP. While you can learn about SOAP as you
+go along, writing Axis clients and servers is not the right time to be
+learning foundational Java concepts, such as what an array is, or basic
+application server concepts such as how servlets work, and the basics
+of the HTTP protocol.
+<p> Things you need to know before writing a Web Service: </p>
+<ol>
+ <li> Core Java datatypes, classes and programming concepts. </li>
+ <li> What threads are, race conditions, thread safety and
+sychronization. </li>
+ <li> What a classloader is, what hierarchical classloaders are, and
+the common causes of a "ClassNotFoundException". </li>
+ <li> How to diagnose trouble from exception traces, what a
+NullPointerException (NPE) and other common exceptions are, and how to
+fix them. </li>
+ <li> What a web application is; what a servlet is, where classes,
+libraries and data go in a web application. </li>
+ <li> How to start your application server and deploy a web
+application on it. </li>
+ <li> What a network is, the core concepts of the IP protocol suite
+and the sockets API. Specifically, what is TCP/IP. </li>
+ <li> What HTTP is. The core protocol and error codes, HTTP headers
+and perhaps the details of basic authentication. </li>
+ <li> What XML is. Not necessarily how to parse it or anything, just
+what constitutes well-formed and valid XML. </li>
+</ol>
+Axis and SOAP depends on all these details. If you don't know them,
+Axis (or anyone else's Web Service middleware) is a dangerous place to
+learn. Sooner or later you will be forced to discover these details,
+and there are easier places to learn than Axis.
+<p> If you are completely new to Java, we recommend you start off with
+things like the Java Tutorials on Sun's web site, and perhaps a classic
+book like <a href="http://www.mindview.net/Books/TIJ/">Thinking in Java</a>,
+until you have enough of a foundation to be able to work with Axis. It
+is also useful to have written a simple web application, as this will
+give you some knowledge of how HTTP works, and how Java application
+servers integrate with HTTP. </p>
+<p> Be aware that there is a lot more needed to be learned in order to
+use Axis and SOAP effectively than the listing above. The other big
+area is "how to write internet scale distributed applications". Nobody
+knows how to do that properly yet, so that you have to learn this by
+doing. </p>
+<h2>Step 0: Concepts</h2>
+Apache Axis is an Open Source SOAP server and client. SOAP is a
+mechanism for inter-application communication between systems written
+in arbitrary languages, across the Internet. SOAP usually exchanges
+messages over HTTP: the client POSTs a SOAP request, and receives
+either an HTTP success code and a SOAP response or an HTTP error code.
+Open Source means that you get the source, but that there is no formal
+support organisation to help you when things go wrong.
+<p> SOAP messages are XML messages. These messages exchange structured
+information between SOAP systems. Messages consist of one or more SOAP
+elements inside an envelope, Headers and the SOAP Body. SOAP has two
+syntaxes for describing the data in these elements, <i>Section 5</i>,
+which is a clear descendant of the XML RPC system, and <i>XML Schema</i>,
+which is the newer (and usually better) system. Axis handles the magic
+of converting Java objects to SOAP data when it sends it over the wire
+or receives results. SOAP Faults are sent by the server when something
+goes wrong; Axis converts these to Java exceptions. </p>
+<p> SOAP is intended to link disparate systems. It is not a mechanism
+to tightly bind Java programs written by the same team together. It can
+bind Java programs together, but not as tightly as RMI or Corba. If you
+try sending many Java objects that RMI would happily serialize, you
+will be disappointed at how badly Axis fails. This is by design: if
+Axis copied RMI and serialized Java objects to byte streams, you would
+be stuck to a particular version of Java everywhere. </p>
+<p> Axis implements the JAX-RPC API, one of the standard ways to
+program Java services. If you look at the specification and tutorials
+on Sun's web site, you will understand the API. If you code to the API,
+your programs will work with other implementations of the API, such as
+those by Sun and BEA. Axis also provides extension features that in
+many ways extends the JAX-RPC API. You can use these to write better
+programs, but these will only work with the Axis implementation. But
+since Axis is free and you get the source, that should not matter. </p>
+<p> Axis is compiled in the JAR file <i>axis.jar</i>; it implements
+the JAX-RPC API declared in the JAR files <i>jaxrpc.jar</i> and <i>saaj.jar</i>.
+It needs various helper libraries, for logging, WSDL processing and
+introspection. All these files can be packaged into a web application, <i>axis.war</i>,
+that can be dropped into a servlet container. Axis ships with some
+sample SOAP services. You can add your own by adding new compiled
+classes to the Axis webapp and registering them. </p>
+<p> Before you can do that, you have to install it and get it working. </p>
+<a name="webapp"></a>
+<h2>Step 1: Preparing the webapp</h2>
+<p> Here we assume that you have a web server up and running on the
+localhost at port 8080. If your server is on a different port, replace
+references to 8080 to your own port number. </p>
+<p>In your Application Server 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. <a name="depend"></a> </p>
+<h2>Step 2: Setting up the libraries</h2>
+<p>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.</p>
+<p> Axis needs to be able to find an XML parser. If your application
+server or Java runtime does not make one visible to web applications,
+you need to download and add it. Java 1.4 includes the Crimson parser,
+so you <i>can</i> omit this stage, though the Axis team prefer Xerces.
+</p>
+<p> To add an XML parser, acquire the JAXP 1.1 XML compliant parser of
+your choice. We recommend Xerces jars from the <a
+ href="http://xml.apache.org/dist/xerces-j/">xml-xerces distribution</a>,
+though others mostly work. Unless your JRE or app server has its own
+specific requirements, you can add the parser's libraries to
+axis/WEB-INF/lib. The examples in this guide use Xerces.
+This guide adds xml-apis.jar and xercesImpl.jar to the AXISCLASSPATH so
+that Axis can find the parser (<a href="#Classpath_setup">see below</a>).<br>
+</p>
+<p>If you get ClassNotFound errors relating to Xerces or DOM then you
+do not have an XML parser installed, or your CLASSPATH (or
+AXISCLASSPATH) variables are not correctly configured.<br>
+</p>
+<h3>Tomcat 4.x and Java 1.4</h3>
+Java 1.4 changed the rules as to to how packages beginning in java.*
+and javax.* get loaded. Specifically, they only get loaded from <i>endorsed</i>
+directories. jaxrpc.jar and saaj.jar contain javax packages, so they
+may not get picked up. If happyaxis.jsp (see below) cannot find the
+relevant packages, copy them from axis/WEB-INF/lib to
+CATALINA_HOME/common/lib and restart Tomcat. <a name="start"></a>
+<h2>Step 3: starting the web server</h2>
+<p>This varies on a product-by-product basis. In many cases it is as
+simple as double clicking on a startup icon or running a command from
+the command line.</p>
+<a name="install-test"></a>
+<h2>Step 4: Validate the Installation</h2>
+<p> After installing the web application and dependencies, you should
+make sure that the server is running the web application. </p>
+<h3> Look for the start page </h3>
+Navigate to the start page of the webapp, usually <a
+ href="http://127.0.0.1:8080/axis/">http://127.0.0.1:8080/axis/</a>,
+though of course the port may differ.<br>
+<br>
+You should now see an Apache-Axis start page. If you do not, then the
+webapp is not actually installed, or the appserver is not running.
+<h3>Validate Axis with happyaxis</h3>
+Follow the link <i> Validate the local installation's configuration</i><br>
+This will bring you to <i>happyaxis.jsp</i> a test page that verifies
+that needed and optional libraries are present. The URL for this will
+be something like <a href="http://localhost:8080/axis/happyaxis.jsp">
+http://localhost:8080/axis/happyaxis.jsp</a>
+<p> If any of the needed libraries are missing, Axis will not work. <br>
+<b>You must not proceed until all needed libraries can be found, and
+this validation page is happy.</b> <br>
+Optional components are optional; install them as your need arises. If
+you see nothing but an internal server error and an exception trace,
+then you probably have multiple XML parsers on the CLASSPATH (or
+AXISCLASSPATH), and this
+is causing version confusion. Eliminate the extra parsers, restart the
+app server and try again. </p>
+<h3>Look for some services</h3>
+<p> From the start page, select <i>View the list of deployed Web
+services</i>. 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 <i>(wsdl)</i> for each deployed Web service to make sure that
+your web service is up and running. </p>
+<p> Note that the 'instant' JWS Web Services that Axis supports are not
+listed in this listing here. The install guide covers this topic
+in detail.<br>
+</p>
+<h3>Test a SOAP Endpoint</h3>
+Now it's time to test a service. Although SOAP 1.1 uses HTTP POST to
+submit an XML request to the <i>endpoint</i>, Axis also supports a
+crude HTTP GET access mechanism, which is useful for testing. First
+let's retrieve the version of Axis from the version endpoint, calling
+the <code>getVersion</code> method:<br>
+<br>
+<a href="http://localhost:8080/axis/services/Version?method=getVersion">http://localhost:8080/axis/services/Version?method=getVersion
+</a><br>
+<br>
+This should return something like:
+<pre class="xml"> <?xml version="1.0" encoding="UTF-8" ?> <br> <soapenv:Envelope <br> xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" <br> xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><br> <soapenv:Body><br> <getVersionResponse <br> soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><br> <getVersionReturn <br> xsi:type="xsd:string"><br> Apache Axis version: 1.1 Built on Apr 04, 2003 (01:30:37 PST)<br> </getVersionReturn> <br> </getVersionResponse><br> </soapenv:Body><br> </soapenv:Envelope><br></pre>
+The Axis version and build date may of course be different.
+<h3>Test a JWS Endpoint</h3>
+Now let's test a JWS web service. Axis' JWS Web Services are java files
+you save into the Axis webapp <i>anywhere but the WEB-INF tree</i>,
+giving them the .jws extension. When someone requests the .jws file by
+giving its URL, it is compiled and executed. The user guide covers JWS
+pages in detail.
+<p> To test the JWS service, we make a request against a built-in
+example, EchoHeaders.jws (look for this in the axis/ directory). </p>
+<p> Point your browser at <a
+ href="http://localhost:8080/axis/EchoHeaders.jws?method=list">
+http://localhost:8080/axis/EchoHeaders.jws?method=list </a>.</p>
+<p> This should return an XML listing of your application headers, such
+as </p>
+<pre class="xml"><?xml version="1.0" encoding="UTF-8" ?> <br><soapenv:Envelope <br> xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" <br> xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><br> <soapenv:Body><br> <listResponse <br> soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><br> <listReturn xsi:type="soapenc:Array" <br> soapenc:arrayType="xsd:string[6]" <br> xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"><br> <item>accept:image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*</item> <br> <item>accept-language:en-us</item> <br> <item>accept-encoding:gzip, deflate</item> <br> <item>user-agent:Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)</item> <br> <item>host:localhost:8080</item> <br> <item>connection:Keep-Alive</item> <br> </listReturn><br> </listResponse><br> </soapenv:Body><br></soapenv:Envelope><br><br></pre>
Again, the exact return values will be different, and you may need to
-change URLs to correct any host, port and webapp specifics.
-
- <a name="websvc"/></a>
- <h2>Step 5: Installing new Web Services</h2>
-
- <p>So far you have got Axis installed and working--now it is time to add
- your own Web Service.
- <p>
- The process here boils down to (1) get the classes and libraries of your
- new service into the Axis WAR directory tree, and (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. Both of
- these do the same thing: they run the Axis SOAP client to talk to the
- Axis adminstration service, which is a SOAP service in
- its own right. It's also a special SOAP service in one regard--it is restricted to
- local callers only (not remote access) and is password protected to stop
- random people from administrating your service.
- There is a default password that the client knows; if you change it
- then you need to pass the new password to the client.
- </p>
- <p>
- The first step is to add your code to the server.
-
- <p>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.
-
- <p>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.</p>
-
- <p>
- 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.
-
- <p><span class="note">Note:</span> If your web service uses
- the simple authorization handlers provided with xml-axis (this is actually
- <u>not</u> 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 users.lst file into the WEB-INF directory.</p>
-
- <a name="deploy"/></a>
- <h2>Step 6: Deploying your Web Service</h2>
- </table>
-
- <p>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 (WSDD) file that
- describes in XML what the service is, what methods it exports and
- other aspects of the SOAP endpoint.
- <p>
-
- The users guide and reference guide cover these WSDD files; here we
- are going to use one from the Axis samples: the stock quote service.
-
- <h3>Classpath setup</h3>
-
- Add axis.jar, commons-discovery.jar, commons-logging.jar, jaxrpc.jar, saaj.jar,
- log4j-1.2.8.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.
-
- On Windows, this can be done via something like the following, though of course
- to store this information permanently in WinNT systems dialog boxes
- would be used:
-<pre class="xml">
- set AXIS_HOME=c:\tomcat\webapps\axis
- set AXIS_LIB=%AXIS_HOME%\lib
- set AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery.jar;
- %AXIS_LIB%\commons-logging.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;
- %AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\xml-apis.jar;%AXIS_LIB%\xercesImpl.jar
-</pre>
- Unix users have to do something similar:
-<pre class="xml">
- set AXIS_HOME=/usr/tomcat/webapps/axis
- set AXIS_LIB=$AXIS_HOME/lib
- set AXISCLASSPATH=$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery.jar:
- $AXIS_LIB/commons-logging.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/saaj.jar:
- $AXIS_LIB/log4j-1.2.8.jar:$AXIS_LIB/xml-apis.jar:$AXIS_LIB/xercesImpl.jar
- export AXIS_HOME; export AXIS_LIB; export AXISCLASSPATH
-</pre>
-
- To use Axis client code, you can select the Axis classpath when invoking
- Java by entering
-
- <pre class="xml">java -cp "%AXISCLASSPATH%" ...</pre>
- or
- <pre class="xml">java -cp "$AXISCLASSPATH" ...</pre>
- depending on the platform. You may omit the quotes if your classpath
- doesn't have spaces in it.
-
- <h3>Find the deployment descriptor</h3>
-
- <p>
-
- Look in axis/samples/stock for the file deploy.wsdd. This is the
- deployment descriptor we want to tell Axis about. Deployment
- descriptors are an Axis-specific XML file that tells Axis how to
- deploy (or undeploy) a Web Service, and how to configure Axis
- itself. The Axis Administration Web Service lets the AdminClient
- program and its Ant task counterpart submit a new WSDD file for
- interpretation. The Axis 'engine' will update its configuration,
- then save its state.
-
- <p>
-
- By default Axis saves it state into the global configuration file
- axis/WEB-INF/server-config.wsdd. Sometimes you see a warning message
- about such a file not being found--don't worry about this, because
- Axis auto-creates the file after you deploy something to it.
- You can check in the webapp to see what this file looks like--and
- even copy it to other systems if you want to give them identical
- configurations. Note that Axis needs an expanded web application
- <i>and</i> write access to the WEB-INF dir to save its state in this
- location.
-
- <h3>Run the admin client</h3>
-
- Execute the following command from the samples/stock directory:
- <blockquote>
- <code class="java">java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient <br>
- -lhttp://localhost:8080/axis/services/AdminService deploy.wsdd</code>
- </blockquote>
-
- If you get some java client error (like ClassNotFoundException),
- then you haven't set up your classpath right, mistyped the
- classname, or did some other standard error. Tracking down such
- problems are foundational Java development skills--if you don't know
- how to do these things, learn them now!
-
- <p><span class="note">Note:</span>
- 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
- to something other than "axis" change the URL appropriately.</p>
-
-
- <p>
- If you get some AxisFault listing, then the client is working, but
- the deployment was unsuccessful. This is where the knowledge of the
- sockets API to TCP and the basics of the HTTP that Web Service
- development requires begins to be needed. If you got some socket
- error like connection refused, well, clearly the computer at the far
- end isn't talking to you, so find the cause of that and fix it. If you
- get an HTTP error code back, well, you know what the error codes
- mean, right? If you are going to develop Web Services--you will need to!
-
- </p>
-
- <p>
-
- The <a href="user-guide.html">user's guide</a> covers the
- AdminClient in more detail, and there is also an
- <a href="ant/axis-admin.html">Ant task</a> to automate the use of Axis in your
- Ant build scripts.
-
- </p>
-
- <a name="test"/></a>
- <h2>Step 7: Testing</h2>
-
- <p>This step is optional, but highly recommended. For illustrative
- purposes, it is presumed that you have installed and deployed the stock quote
- demo.</p>
- <ul>
- <li>
- Change directory to the distribution directory for xml-axis
- and execute the following command (or its Unix equivalent):
- <blockquote>
- <code class="java">java -cp "%AXISCLASSPATH%" samples.stock.GetQuote <br>
- -lhttp://localhost:8080/axis/servlet/AxisServlet -uuser1 -wpass1 XXX</code>
- </blockquote>
- </li>
- <li>You should get back "55.25" as a result.</li>
- </ul>
-
- <p><span class="note">Note:</span>
- 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 to
- something other than "axis" change the URL appropriately.
- </p>
-
-
- <a name="advanced"/></a>
-
- <h2>Advanced Installation: adding Axis to your own Webapp</h2>
-
- If you are experienced in web application development, and especially if you
- wish to add web services to an existing or complex webapp, you can
- take an alternate approach to running Axis. Instead of adding your
- classes to the Axis webapp, you can add Axis to your application.
- <p>
- The core concepts are
- <ol>
- <li>Add axis.jar, wsdl.jar, saaj.jar, jaxrpc.jar and the other
- dependent libraries to your WAR file.
- <li>Copy all the Axis Servlet declarations and mappings from
- axis/WEB-INF/web.xml and add them to your own web.xml
- <li>Build and deploy your webapp.
- <li>Run the Axis AdminClient against your own webapp, instead of
- Axis, by changing the URL you invoke it with.
- </ol>
-
- The process is also covered in Chapter 15 of
- <A href="http://manning.com/antbook">Java Development with Ant</A>,
- which can be downloaded as a
- <A href="http://www.manning.com/hatcher/chap15.pdf">PDF file</A>.
-
-
- <a name="broken"/></a>
-
- <h2>What if it doesn't work?</h2>
-
- Axis is a complicated system to install. This is because it depends
- on the underlying functionality of your app server, has a fairly
- complex configuration, and, like all distributed applications,
- depends upon the network too.
-
- <p>
-
- We see a lot of people posting their problems on the axis-user
- mailing list, and other Axis users as well as the Axis developers do their
- best to help when they can. But before you rush to post your own
- problems to the mailing list, a word of caution:
-
- <p>
-
- Axis is free. This means nobody gets paid to man the support lines.
- All the help you get from the community is voluntary and
- comes from the kindness of their hearts. They may be other users,
- willing to help you get past the same hurdles they had to be helped
- over, or they may be the developers themselves. But it is all
- voluntary, so you may need to keep your expectations low!
-
- <ol>
-
-
- <li>Post to the user mail list, not the developer list. You may
- think the developer mail list is a short cut to higher quality
- answers. But the developers are also on the user list along with many
- other skilled users--so more people will be able to answer your questions.
- Also, it is helpful for all user issues to be on one list to help build
- the searchable mailing list archive.
-
- </li>
-
- <li>
- Don't ask non-Axis-related questions. The list is not the place to
- ask about non-Axis, non-SOAP, problems. Even questions about the MS
- Soap toolkit or .NET client side, don't get many positive answers--we
- avoid them. That also goes for the Sun Java Web Services Developer
- Pack, or the Jboss.net stuff that they've done with Axis.
- </li>
-
- <li>Never bother posting to the soapbuilders mailing list
- either, that is only for people developing SOAP toolkits, not using
- them--all off-topic messages are pointedly ignored.
- </li>
-
- <li>
- There is no guarantee that anyone will be able to solve your
- problem. The usual response in such a situation is silence, for
- a good reason: if everybody who didn't know the answer to a question
- said "I don't know", the list would be overflowed with noise. Don't
- take silence personally.
-
- <li>
- Never expect an immediate answer. Even if someone knows the answer,
- it can take a day or two before they read their mail. So if you don't
- get an answer in an hour or two, don't panic and resend. Be patient.
- And put the time to use by trying to solve your problems yourself.
- </li>
-
- <li>
- Do your homework first. This document lists the foundational stuff
- you need to understand. It has also warned you that it can take a day
- to get a reply. Now imagine you get a HTTP Error '404' on a SOAP
- call. Should you rush to post a 'help' request, or should you try
- and find out what an HTTP error code is, what #404 usually means and
- how to use a Java debugger. We provide the source to make that
- debugging easier :)
- </li>
-
- <li>
- Post meaningful subject lines. You want your message read, not
- deleted unread. A subject line of 'Axis problem', 'Help with Axis', etc.
- is not meaningful, and is not likely to get many readers.
- </li>
-
- <li>
- Search the <a
- href="http://nagoya.apache.org/eyebrowse/SummarizeList?listId=49">
- mailing list archives</a> FIRST to see if someone had the same problem.
- This list is searchable--and may save you much time in getting an answer
- to your problem.
- </li>
-
- <li>
- Use the <a href="http://nagoya.apache.org/bugzilla/">bugzilla</a>
- database to search for Axis bugs, both open and closed.
- </li>
-
- <li> Consult the
- <a href="http://nagoya.apache.org/wiki/apachewiki.cgi?AxisProjectPages">
- Axis Wiki</a>
- For its Frequently Asked Questions (FAQ), installation notes,
- interoperability issues lists, and other useful information.
- </li>
-
- <li>
-
- Don't email people for help directly, unless you know them. It's rude and
- presumptious. Messages sent over the mail list benefit the whole
- community--both the original posters and people who search the list. Personal
- messages just take up the recipients time, and are unwelcome.
- Usually, if not ignored outright, recipients of personal requests will just
- respond 'ask the mail list' anyway!
- </li>
-
- <li>
- Know that configuration problems are hard to replicate, and so can be difficult to
- get help on. We have tried with the happyaxis.jsp demo to automate the
- diagnostics gathering for you, but it can be hard for people to be of help here,
- especially for obscure platforms.
- </li>
-
- <li>
- Keep up to date with Axis releases, even the beta copies of
- forthcoming releases. You wouldn't want your problem to be a bug that was
- already known and fixed in a more recent release. Often the common response to
- any question is 'have you tried the latest release'.
-
- <li>
- Study and use the source, and fix it when you find defects. Even fix the
- documentation when you find defects. It is only through the participation
- of Axis' users that it will ever get better.
-
- </ol>
-
- Has this put you off joining and participating in the Axis user
- mail list? We hope not--this list belongs to the people who use Axis
- and so will be your peers as your project proceeds. We just need for
- you to be aware that it is not a 24x7 support line for people new to
- server side Java development, and that you will need to be somewhat self
- sufficient in this regard. It is not a silver bullet. However, knowing how to
- make effective use of the list will help you develop better with Axis.
-
-
- <a name="summary"/></a>
- <h2>Summary</h2>
-
- Axis is simply an implementation of SOAP which can be added to your
- own webapp, and a webapp which can host your own web services.
- Installing it can be a bit fiddly, especially given Java 1.4's
- stricter requirements. If you follow a methodical process, including testing
- along the way, using happyaxis and the bundled test services, you
- will find it easier to get started with Axis.
-
-
-<hr size=1 noshade= />
-<div class=copyright align=center>Copyright © 2001-2003, Apache Software Foundation</div>
- </body>
+change URLs to correct any host, port and webapp specifics. <a
+ name="websvc"></a>
+<h2>Step 5: Installing new Web Services</h2>
+<p>So far you have got Axis installed and working--now it is time to
+add your own Web Service. </p>
+<p> The process here boils down to (1) get the classes and libraries of
+your new service into the Axis WAR directory tree, and (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. Both of these do the same thing: they run the Axis SOAP
+client to talk to the Axis adminstration service, which is a SOAP
+service in its own right. It's also a special SOAP service in one
+regard--it is restricted to local callers only (not remote access) and
+is password protected to stop random people from administrating your
+service. There is a default password that the client knows; if you
+change it then you need to pass the new password to the client. </p>
+<p> The first step is to add your code to the server. </p>
+<p>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. </p>
+<p>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.</p>
+<p> 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. </p>
+<p><span class="note">Note:</span> If your web service uses the simple
+authorization handlers provided with xml-axis (this is actually <u>not</u>
+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 users.lst file into the WEB-INF directory.</p>
+<a name="deploy"></a>
+<h2>Step 6: Deploying your Web Service</h2>
+<p>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 (WSDD) file
+that describes in XML what the service is, what methods it exports and
+other aspects of the SOAP endpoint. </p>
+<p> The users guide and reference guide cover these WSDD files; here we
+are going to use one from the Axis samples: the stock quote service. </p>
+<h3><a name="Classpath_setup"></a>Classpath setup</h3>
+In order for these examples to work, java must be able to find
+axis.jar, commons-discovery.jar, commons-logging.jar, jaxrpc.jar,
+saaj.jar, log4j-1.2.8.jar (or whatever is appropriate for your chosen
+logging implementation), and the XML parser jar file or files (e.g.,
+xerces.jar). These examples do this by adding these files to
+AXISCLASSPATH and then specifying the AXISCLASSPATH when you run them.
+Also for these examples, we have copied the
+xml-apis.jar and xercesImpl.jar files into the AXIS_LIB
+directory. An
+alternative would be to add your XML parser's jar file directly to the
+AXISCLASSPATH variable or to add all these files to your CLASSPATH
+variable.<br>
+<br>
+On Windows, this can be done via the following. For this document we
+assume that you have installed Axis in C:\axis. To store this
+information
+permanently in WinNT/2000/XP you will need to right click on "My
+Computer" and select "Properties". Click the "Advanced" tab and create
+the new environmental variables. It is often better to use
+WordPad to create the variable string and then paste it into the
+appropriate text field.<br>
+<pre class="xml"> set AXIS_HOME=c:\axis<br> set AXIS_LIB=%AXIS_HOME%\lib<br> set AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery.jar;<br> %AXIS_LIB%\commons-logging.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;<br> %AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\xml-apis.jar;%AXIS_LIB%\xercesImpl.jar<br></pre>
+Unix users have to do something similar. Below we have installed AXIS
+into /usr/axis and are using the bash shell. See your shell's
+documentation for differences. To make variables permenate you will
+need to add them to your shell's startup (dot) files. Again, see your
+shell's documentation.
+<pre class="xml"> set AXIS_HOME=/usr/axis<br> set AXIS_LIB=$AXIS_HOME/lib<br> set AXISCLASSPATH=$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery.jar:<br> $AXIS_LIB/commons-logging.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/saaj.jar:<br> $AXIS_LIB/log4j-1.2.8.jar:$AXIS_LIB/xml-apis.jar:$AXIS_LIB/xercesImpl.jar<br> export AXIS_HOME; export AXIS_LIB; export AXISCLASSPATH<br></pre>
+To use Axis client code, you can select AXISCLASSPATH when
+invoking Java by entering
+<pre class="xml">java -cp %AXISCLASSPATH% ...</pre>
+or
+<pre class="xml">java -cp "$AXISCLASSPATH" ...</pre>
+depending on the platform. You may omit the quotes if your CLASSPATH
+doesn't have spaces in it.<br>
+<br>
+Also, it is probably a good time to add the AXISCLASSPATH variable to
+your CLASSPATH variable. This will enable you to not include the
+AXISCLASSPATH variable when launching the examples in this guide.
+This document assumes that you have NOT done this.<br>
+<h3>Find the deployment descriptor</h3>
+<p> Look in axis/samples/stock for the file deploy.wsdd. This is the
+deployment descriptor we want to tell Axis about. Deployment
+descriptors are an Axis-specific XML file that tells Axis how to deploy
+(or undeploy) a Web Service, and how to configure Axis itself. The Axis
+Administration Web Service lets the AdminClient program and its Ant
+task counterpart submit a new WSDD file for interpretation. The Axis
+'engine' will update its configuration, then save its state. </p>
+<p> By default Axis saves it state into the global configuration file
+axis/WEB-INF/server-config.wsdd. Sometimes you see a warning message
+about such a file not being found--don't worry about this, because Axis
+auto-creates the file after you deploy something to it. You can check
+in the webapp to see what this file looks like--and even copy it to
+other systems if you want to give them identical configurations. Note
+that Axis needs an expanded web application <i>and</i> write access to
+the WEB-INF dir to save its state in this location. </p>
+<h3>Run the admin client</h3>
+Execute the following command from the samples/stock directory.
+If you are not in this directory you will get a
+"java.io.FileNotFoundException:
+deploy.wsdd (The system cannot find the file specified)" exception.
+<blockquote> <b>On Windows</b> <br>
+ <code class="java">java -cp %AXISCLASSPATH%
+org.apache.axis.client.AdminClient
+-lhttp://localhost:8080/axis/services/AdminService deploy.wsdd<br>
+ </code> <b><br>
+On UNIX</b> <br>
+ <code class="java">java -cp $AXISCLASSPATH
+org.apache.axis.client.AdminClient <br>
+-lhttp://localhost:8080/axis/services/AdminService deploy.wsdd</code> </blockquote>
+If you get some java client error (like ClassNotFoundException), then
+you haven't set up your AXISCLASSPATH (or CLASSPATH) variable right,
+mistyped the
+classname, or did some other standard error. Tracking down such
+problems are foundational Java development skills--if you don't know
+how to do these things, learn them now!
+<p><span class="note">Note:</span> 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 to something other than
+"axis" change the URL appropriately.</p>
+<p> If you get some AxisFault listing, then the client is working, but
+the deployment was unsuccessful. This is where the knowledge of the
+sockets API to TCP and the basics of the HTTP that Web Service
+development requires begins to be needed. If you got some socket error
+like connection refused, the computer at the far end
+isn't talking to you, so find the cause of that and fix it. If you get
+an HTTP error code back find out what the error means and correct the
+problem. These skills are fundamental to using web services.<br>
+</p>
+<p> The <a href="user-guide.html">user's guide</a> covers the
+AdminClient in more detail, and there is also an <a
+ href="ant/axis-admin.html">Ant task</a> to automate the use of Axis in
+your Ant build scripts. </p>
+<a name="test"></a>
+<h2>Step 7: Testing</h2>
+<p>This step is optional, but highly recommended. For illustrative
+purposes, it is presumed that you have installed and deployed the stock
+quote demo.</p>
+<ul>
+ <li> Change directory to the distribution directory for xml-axis and
+execute the following command (or its Unix equivalent):
+ <blockquote> <b>On Windows</b> <code class="java"><br>
+java -cp .;%AXISCLASSPATH% samples.stock.GetQuote <br>
+-lhttp://localhost:8080/axis/servlet/AxisServlet -uuser1 -wpass1 XXX</code><br>
+ <br>
+ <span style="font-weight: bold;">On UNIX</span><br>
+ <code class="java">java -cp $AXISCLASSPATH samples.stock.GetQuote
+ <br>
+-lhttp://localhost:8080/axis/servlet/AxisServlet -uuser1 -wpass1 XXX</code> <code
+ class="java"></code><br>
+ <br>
+ </blockquote>
+ </li>
+ <li>You should get back "55.25" as a result.</li>
+</ul>
+<p><span class="note">Note:</span> 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 to something
+other than "axis" change the URL appropriately. </p>
+<a name="advanced"></a>
+<h2>Advanced Installation: adding Axis to your own Webapp</h2>
+If you are experienced in web application development, and especially
+if you wish to add web services to an existing or complex webapp, you
+can take an alternate approach to running Axis. Instead of adding your
+classes to the Axis webapp, you can add Axis to your application.
+<p> The core concepts are </p>
+<ol>
+ <li>Add axis.jar, wsdl.jar, saaj.jar, jaxrpc.jar and the other
+dependent libraries to your WAR file. </li>
+ <li>Copy all the Axis Servlet declarations and mappings from
+axis/WEB-INF/web.xml and add them to your own web.xml </li>
+ <li>Build and deploy your webapp. </li>
+ <li>Run the Axis AdminClient against your own webapp, instead of
+Axis, by changing the URL you invoke it with. </li>
+</ol>
+The process is also covered in Chapter 15 of <a
+ href="http://manning.com/antbook">Java Development with Ant</a>, which
+can be downloaded as a <a
+ href="http://www.manning.com/hatcher/chap15.pdf">PDF file</a>. <a
+ name="broken"></a>
+<h2>What if it doesn't work?</h2>
+Axis is a complicated system to install. This is because it depends on
+the underlying functionality of your app server, has a fairly complex
+configuration, and, like all distributed applications, depends upon the
+network too.
+<p> We see a lot of people posting their problems on the axis-user
+mailing list, and other Axis users as well as the Axis developers do
+their best to help when they can. But before you rush to post your own
+problems to the mailing list, a word of caution: </p>
+<p> Axis is free. This means nobody gets paid to man the support lines.
+All the help you get from the community is voluntary and comes from the
+kindness of their hearts. They may be other users, willing to help you
+get past the same hurdles they had to be helped over, or they may be
+the developers themselves. But it is all voluntary, so you may need to
+keep your expectations low! </p>
+<ol>
+ <li>Post to the <a href="mailto:axis-user@ws.apache.org">user mail</a>
+list, not the developer list. You may think the developer mail list is
+a short cut to higher quality answers. But the developers are also on
+the user list along with many other skilled users--so more people will
+be able to answer your questions. Also, it is helpful for all user
+issues to be on one list to help build the searchable mailing list
+archive. </li>
+ <li> Don't ask non-Axis-related questions. The list is not the place
+to ask about non-Axis, non-SOAP, problems. Even questions about the MS
+Soap toolkit or .NET client side, don't get many positive answers--we
+avoid them. That also goes for the Sun Java Web Services Developer
+Pack, or the Jboss.net stuff that they've done with Axis. </li>
+ <li>Never bother posting to the soapbuilders mailing list either,
+that is only for people developing SOAP toolkits, not using them--all
+off-topic messages are pointedly ignored. </li>
+ <li> There is no guarantee that anyone will be able to solve your
+problem. The usual response in such a situation is silence, for a good
+reason: if everybody who didn't know the answer to a question said "I
+don't know", the list would be overflowed with noise. Don't take
+silence personally. </li>
+ <li> Never expect an immediate answer. Even if someone knows the
+answer, it can take a day or two before they read their mail. So if you
+don't get an answer in an hour or two, don't panic and resend. Be
+patient. And put the time to use by trying to solve your problems
+yourself. </li>
+ <li> Do your homework first. This document lists the foundational
+stuff you need to understand. It has also warned you that it can take a
+day to get a reply. Now imagine you get a HTTP Error '404' on a SOAP
+call. Should you rush to post a 'help' request, or should you try and
+find out what an HTTP error code is, what #404 usually means and how to
+use a Java debugger. We provide the source to make that debugging
+easier :) </li>
+ <li> Post meaningful subject lines. You want your message read, not
+deleted unread. A subject line of 'Axis problem', 'Help with Axis',
+etc. is not meaningful, and is not likely to get many readers. </li>
+ <li> Search the <a
+ href="http://nagoya.apache.org/eyebrowse/SummarizeList?listId=49">
+mailing list archives</a> FIRST to see if someone had the same problem.
+This list is searchable--and may save you much time in getting an
+answer to your problem. </li>
+ <li> Use the <a href="http://nagoya.apache.org/bugzilla/">bugzilla</a>
+database to search for Axis bugs, both open and closed. </li>
+ <li> Consult the <a
+ href="http://nagoya.apache.org/wiki/apachewiki.cgi?AxisProjectPages">
+Axis Wiki</a> For its Frequently Asked Questions (FAQ), installation
+notes, interoperability issues lists, and other useful information. </li>
+ <li> Don't email people for help directly, unless you know them. It's
+rude and presumptious. Messages sent over the mail list benefit the
+whole community--both the original posters and people who search the
+list. Personal messages just take up the recipients time, and are
+unwelcome. Usually, if not ignored outright, recipients of personal
+requests will just respond 'ask the mail list' anyway! </li>
+ <li> Know that configuration problems are hard to replicate, and so
+can be difficult to get help on. We have tried with the happyaxis.jsp
+demo to automate the diagnostics gathering for you, but it can be hard
+for people to be of help here, especially for obscure platforms. </li>
+ <li> Keep up to date with Axis releases, even the beta copies of
+forthcoming releases. You wouldn't want your problem to be a bug that
+was already known and fixed in a more recent release. Often the common
+response to any question is 'have you tried the latest release'. </li>
+ <li> Study and use the source, and fix it when you find defects. Even
+fix the documentation when you find defects. It is only through the
+participation of Axis' users that it will ever get better. </li>
+</ol>
+Has this put you off joining and participating in the Axis user mail
+list? We hope not--this list belongs to the people who use Axis and so
+will be your peers as your project proceeds. We just need for you to be
+aware that it is not a 24x7 support line for people new to server side
+Java development, and that you will need to be somewhat self sufficient
+in this regard. It is not a silver bullet. However, knowing how to make
+effective use of the list will help you develop better with Axis. <a
+ name="summary"></a>
+<h2>Summary</h2>
+Axis is simply an implementation of SOAP which can be added to your own
+webapp, and a webapp which can host your own web services. Installing
+it can be a bit fiddly, especially given Java 1.4's stricter
+requirements. If you follow a methodical process, including testing
+along the way, using happyaxis and the bundled test services, you will
+find it easier to get started with Axis.
+<hr size="1" noshade="noshade">
+<div class="copyright" align="center">Copyright © 2001-2003,
+Apache Software Foundation</div>
+</body>
</html>