Google Git
Sign in
apache / axis-axis1-java / c07d27c2476597f249055e05820a28af042fba60 / . / docs / install.html
blob: e6801a40f9371aaa67b964922a19f4bf086c7f8e [file] [log] [blame]
<!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">
<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="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="#soapmon">Appendix: Enabling the SOAP Monitor</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>
<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.
You may find the course notes from
<a href="http://www.cs.indiana.edu/classes/a348-dger/fall2002/notes/">
Mastering the World Wide Web</a> useful in this regard, even though Axis
is only introduced in lecture 28.
</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.&nbsp; The examples in this guide use Xerces.&nbsp;
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>
<h3>WebLogic 8.1</h3>
WebLogic 8.1 ships with <code>webservices.jar</code> that conflicts with Axis'
<code>saaj.jar</code> and prevents Axis 1.2 from working right out of the box.
This conflict exists because WebLogic uses an older definition of
<code>javax.xml.soap.*</code> package from
<a href="http://java.sun.com/webservices/docs/1.0/api/javax/xml/soap">
Java Web Services Developer Pack Version 1.0</a>, whereas Axis uses a newer
revision from J2EE 1.4.
<p>
However, there are two alternative configuration changes that enable Axis based
web services to run on Weblogic 8.1.</p>
<ul>
<li>In a webapp containing Axis, set &lt;prefer-web-inf-classes&gt; element in
<code>WEB-INF/weblogic.xml</code> to true. An example of <code>weblogic.xml</code>
is shown below:
<pre>
&lt;weblogic-web-app&gt;
&lt;container-descriptor&gt;
&lt;prefer-web-inf-classes&gt;true&lt;/prefer-web-inf-classes&gt;
&lt;/container-descriptor&gt;
&lt;/weblogic-web-app&gt;
</pre>
<p>
If set to <code>true</code>, the <code>&lt;prefer-web-inf-classes&gt;</code>
element will force WebLogic's classloader to load classes located in the
WEB-INF directory of a web application in preference to application or system
classes. This is a recommended approach since it only impacts a single web module.</p>
</li>
<li>In a script used to start WebLogic server, modify <code>CLASSPATH</code>
property by placing Axis's <code>saaj.jar</code> library in front of WeLlogic's
<code>webservices.jar</code>. <b>NOTE:</b> This approach impacts all applications
deployed on a particular WebLogic instance and may prevent them from using
WebLogic's webservices.</li>
</ul>
<p>For more information on how WebLogic's class loader works, see
<a href="http://e-docs.bea.com/wls/docs81/programming/classloading.html">
WebLogic Server Application Classloading</a>.</p>
<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.&nbsp; 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"> &lt;?xml version="1.0" encoding="UTF-8" ?&gt; <br> &lt;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"&gt;<br> &lt;soapenv:Body&gt;<br> &lt;getVersionResponse <br> soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&gt;<br> &lt;getVersionReturn <br> xsi:type="xsd:string"&gt;<br> Apache Axis version: 1.1 Built on Apr 04, 2003 (01:30:37 PST)<br> &lt;/getVersionReturn&gt; <br> &lt;/getVersionResponse&gt;<br> &lt;/soapenv:Body&gt;<br> &lt;/soapenv:Envelope&gt;<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">&lt;?xml version="1.0" encoding="UTF-8" ?&gt; <br>&lt;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"&gt;<br> &lt;soapenv:Body&gt;<br> &lt;listResponse <br> soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&gt;<br> &lt;listReturn xsi:type="soapenc:Array" <br> soapenc:arrayType="xsd:string[6]" <br> xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"&gt;<br> &lt;item&gt;accept:image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*&lt;/item&gt; <br> &lt;item&gt;accept-language:en-us&lt;/item&gt; <br> &lt;item&gt;accept-encoding:gzip, deflate&lt;/item&gt; <br> &lt;item&gt;user-agent:Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)&lt;/item&gt; <br> &lt;item&gt;host:localhost:8080&lt;/item&gt; <br> &lt;item&gt;connection:Keep-Alive&lt;/item&gt; <br> &lt;/listReturn&gt;<br> &lt;/listResponse&gt;<br> &lt;/soapenv:Body&gt;<br>&lt;/soapenv:Envelope&gt;<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>
<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 &lt;axis-admin&gt;
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).&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; This will enable you to not include the
AXISCLASSPATH variable when launching the examples in this guide.&nbsp;
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.&nbsp;
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>&nbsp;<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.&nbsp; 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>&nbsp;<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.
<h2> <a NAME="soapmon"></a>Appendix: Enabling the SOAP Monitor </h2>
<p>
SOAP Monitor allows for the monitoring of SOAP requests and responses via
a web browser with Java plug-in 1.3 or higher. For a more comprehensive
explanation of its usage, read <a href="user-guide.html#soapmon">Using the
SOAP Monitor</a> in the User's Guide.
</p><p>
By default, the SOAP Monitor is not enabled. The basic steps for enabling
it are compiling the SOAP Monitor java applet, deploying the SOAP Monitor
web service and adding request and response flow definitions for each monitored
web service. In more detail:
<ol>
<li> Go to $AXIS_HOME/webapps/axis (or %AXIS_HOME%\webapps\axis)
and compile SOAPMonitorApplet.java.
<blockquote> <span style="font-weight: bold;">On Windows</span>
<code class="java"><br/>
javac -classpath %AXIS_HOME%\lib\axis.jar SOAPMonitorApplet.java</code><br/>
<br/>
<span style="font-weight: bold;">On Unix</span>
<code class="java"><br/>
javac -classpath $AXIS_HOME/lib/axis.jar SOAPMonitorApplet.java</code><br/>
</blockquote>
Copy all resulting class files (i.e. SOAPMonitorApplet*.class) to the root
directory of the web application using the SOAP Monitor
(e.g. .../tomcat/webapps/axis)
</li>
<li> Deploy the SOAPMonitorService web service with the admin client and the
deploy-monitor.wsdd file (shown below).
<blockquote>Go to the directory deploy-monitor.wsdd is located and execute
the command below. The command assume that /axis is the intended
web application and it is available on port 8080.<br/>
<b>On Windows</b> <br/>
<code class="java">java -cp %AXISCLASSPATH%
org.apache.axis.client.AdminClient
-lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd<br/>
</code>&nbsp;<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-monitor.wsdd</code> </blockquote>
<span style="font-weight: bold;">SOAPMonitorService Deployment Descriptor (deploy-monitor.wsdd)</span>
<pre class="xml">&lt;deployment xmlns=&quot;http://xml.apache.org/axis/wsdd/&quot;
xmlns:java=&quot;http://xml.apache.org/axis/wsdd/providers/java&quot;&gt;
&lt;handler name=&quot;soapmonitor&quot;
type=&quot;java:org.apache.axis.handlers.SOAPMonitorHandler&quot;&gt;
&lt;parameter name=&quot;wsdlURL&quot;
value=&quot;/axis/SOAPMonitorService-impl.wsdl&quot;/&gt;
&lt;parameter name=&quot;namespace&quot;
value=&quot;http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl&quot;/&gt;
&lt;parameter name=&quot;serviceName&quot; value=&quot;SOAPMonitorService&quot;/&gt;
&lt;parameter name=&quot;portName&quot; value=&quot;Demo&quot;/&gt;
&lt;/handler&gt;
&lt;service name=&quot;SOAPMonitorService&quot; provider=&quot;java:RPC&quot;&gt;
&lt;parameter name=&quot;allowedMethods&quot; value=&quot;publishMessage&quot;/&gt;
&lt;parameter name=&quot;className&quot;
value=&quot;org.apache.axis.monitor.SOAPMonitorService&quot;/&gt;
&lt;parameter name=&quot;scope&quot; value=&quot;Application&quot;/&gt;
&lt;/service&gt;
&lt;/deployment&gt;
</pre>
</li>
<li>For each service that is to be monitored, add request and response flow definitions
to the service's deployment descriptor and deploy (or redeploy) the service. The
<span style="font-weight: bold;">requestFlow</span> and <span style="font-weight: bold;">
responseFlow</span> definitions follow the start tag of the <span style="font-weight: bold;">
&lt;service&gt;</span> element. If a service is already deployed, undeploy it and deploy
it with the modified deployment descriptor. An example is shown below:
<pre class="xml">...
&lt;service name=&quot;xmltoday-delayed-quotes&quot; provider=&quot;java:RPC&quot;&gt;
&lt;requestFlow&gt;
&lt;handler type=&quot;soapmonitor&quot;/&gt;
&lt;/requestFlow&gt;
&lt;responseFlow&gt;
&lt;handler type=&quot;soapmonitor&quot;/&gt;
&lt;/responseFlow&gt;
...</pre>
</li>
<li>With a web browser, go to http[s]://host[:port][/webapp]/SOAPMonitor
(e.g. http://localhost:8080/axis/SOAPMonitor) substituting the correct values
for your web application. This will show the SOAP Monitor applet for viewing service
requests and responses. Any requests to services that have been configured
and deployed correctly should show up in the applet.
</li>
<ol>
</p>
<hr size="1" noshade="noshade">
<div class="copyright" align="center">Copyright &copy; 2001-2003,
Apache Software Foundation</div>
</body>
</html>