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 [EMAIL PROTECTED] (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:[EMAIL PROTECTED]">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>
