Installing and deploying web applications using xml-axis |
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 Jakarta Tomcat. [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.
For more details on using Axis, please see the user guide.
Things you need to know before writing a Web Service:
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 Thinking in Java, 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 Mastering the World Wide Web useful in this regard, even though Axis is only introduced in lecture 28.
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.
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, Section 5, which is a clear descendant of the XML RPC system, and XML Schema, 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.
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.
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.
Axis is compiled in the JAR file axis.jar; it implements the JAX-RPC API declared in the JAR files jaxrpc.jar and saaj.jar. It needs various helper libraries, for logging, WSDL processing and introspection. All these files can be packaged into a web application, axis.war, 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.
Before you can do that, you have to install it and get it working.
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.
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.
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.
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 can omit this stage, though the Axis team prefer Xerces.
To add an XML parser, acquire the JAXP 1.1 XML compliant parser of
your choice. We recommend Xerces jars from the xml-xerces distribution,
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 (see below).
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.
webservices.jar that conflicts with Axis'
saaj.jar and prevents Axis 1.4 from working right out of the box.
This conflict exists because WebLogic uses an older definition of
javax.xml.soap.* package from
Java Web Services Developer Pack Version 1.0, whereas Axis uses a newer
revision from J2EE 1.4.
However, there are two alternative configuration changes that enable Axis based web services to run on Weblogic 8.1.
WEB-INF/weblogic.xml to true. An example of weblogic.xml
is shown below:
<weblogic-web-app> <container-descriptor> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor> </weblogic-web-app>
If set to true, the <prefer-web-inf-classes>
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.
CLASSPATH
property by placing Axis's saaj.jar library in front of WeLlogic's
webservices.jar. NOTE: This approach impacts all applications
deployed on a particular WebLogic instance and may prevent them from using
WebLogic's webservices.For more information on how WebLogic's class loader works, see WebLogic Server Application Classloading.
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.
After installing the web application and dependencies, you should make sure that the server is running the web application.
If any of the needed libraries are missing, Axis will not work.
You must not proceed until all needed libraries can be found, and
this validation page is happy.
Optional components are optional; install them as your need arises. 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.
From the start page, select View the list of deployed Web services. This will list all registered Web Services, unless the servlet is configured not to do so. On this page, You should be able to click on (wsdl) for each deployed Web service to make sure that your web service is up and running.
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.
getVersion method:<?xml version="1.0" encoding="UTF-8" ?>The Axis version and build date may of course be different.
<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>
To test the JWS service, we make a request against a built-in example, EchoHeaders.jws (look for this in the axis/ directory).
Point your browser at http://localhost:8080/axis/EchoHeaders.jws?method=list .
This should return an XML listing of your application headers, such as
<?xml version="1.0" encoding="UTF-8" ?>Again, the exact return values will be different, and you may need to change URLs to correct any host, port and webapp specifics.
<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>
So far you have got Axis installed and working--now it is time to add your own Web Service.
The process here boils down to (1) get the classes and libraries of 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.
The first step is to add your code to the server.
In the WEB-INF directory, look for (or create) a "classes" directory (i.e. axis/WEB-INF/classes ). In this directory, copy the compiled Java classes you wish to install, being careful to preserve the directory structure of the Java packages.
If your classes services are already packaged into JAR files, feel free to drop them into the WEB-INF/lib directory instead. Also add any third party libraries you depend on into the same directory.
After adding new classes or libraries to the Axis webapp, you must restart the webapp. This can be done by restarting your application server, or by using a server-specific mechanism to restart a specific webapp.
Note: If your web service uses the simple authorization handlers provided with xml-axis (this is actually not recommended as these are merely illustrations of how to write a handler than intended for production use), then you will need to copy the corresponding users.lst file into the WEB-INF directory.
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.
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.
set AXIS_HOME=c:\axisUnix 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.
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
set AXIS_HOME=/usr/axisTo use Axis client code, you can select AXISCLASSPATH when invoking Java by entering
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
java -cp %AXISCLASSPATH% ...or
java -cp "$AXISCLASSPATH" ...depending on the platform. You may omit the quotes if your CLASSPATH doesn't have spaces in it.
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.
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 and write access to the WEB-INF dir to save its state in this location.
On WindowsIf 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!
java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient -lhttp://localhost:8080/axis/services/AdminService deploy.wsdd
On UNIX
java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
-lhttp://localhost:8080/axis/services/AdminService deploy.wsdd
Note: You may need to replace localhost with your host name, and 8080 with the port number used by your web server. If you have renamed the web application to something other than "axis" change the URL appropriately.
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.
The user's guide covers the AdminClient in more detail, and there is also an Ant task to automate the use of Axis in your Ant build scripts.
This step is optional, but highly recommended. For illustrative purposes, it is presumed that you have installed and deployed the stock quote demo.
On Windows
java -cp .;%AXISCLASSPATH% samples.stock.GetQuote
-lhttp://localhost:8080/axis/servlet/AxisServlet -uuser1 -wpass1 XXX
On UNIX
java -cp $AXISCLASSPATH samples.stock.GetQuote
-lhttp://localhost:8080/axis/servlet/AxisServlet -uuser1 -wpass1 XXX
Note: Again, you may need to replace localhost with your host name, and 8080 with the port number used by your web server. If you have renamed the web application to something other than "axis" change the URL appropriately.
The core concepts are
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:
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!
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 Using the SOAP Monitor in the User's Guide.
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:
On WindowsCopy 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)
javac -classpath %AXIS_HOME%\lib\axis.jar SOAPMonitorApplet.java
On Unix
javac -classpath $AXIS_HOME/lib/axis.jar SOAPMonitorApplet.java
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.SOAPMonitorService Deployment Descriptor (deploy-monitor.wsdd)
On Windows
java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient -lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd
On UNIX
java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
-lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
<handler name="soapmonitor"
type="java:org.apache.axis.handlers.SOAPMonitorHandler">
<parameter name="wsdlURL"
value="/axis/SOAPMonitorService-impl.wsdl"/>
<parameter name="namespace"
value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/>
<parameter name="serviceName" value="SOAPMonitorService"/>
<parameter name="portName" value="Demo"/>
</handler>
<service name="SOAPMonitorService" provider="java:RPC">
<parameter name="allowedMethods" value="publishMessage"/>
<parameter name="className"
value="org.apache.axis.monitor.SOAPMonitorService"/>
<parameter name="scope" value="Application"/>
</service>
</deployment>
...
<service name="xmltoday-delayed-quotes" provider="java:RPC">
<requestFlow>
<handler type="soapmonitor"/>
</requestFlow>
<responseFlow>
<handler type="soapmonitor"/>
</responseFlow>
...