Installing and Configuring Axis | Professional XML Development with Apache Tools: Xerces, Xalan, FOP, Cocoon, Axis, Xindice (Wrox Professional Guides)

The installation procedure for Axis can be a little intimidating because potentially you need to do a lot of things. The first step, as always, is to obtain a current Axis build via http://ws.apache.org/axis. For the sake of example, we’ll assume you want to work with an Axis 1.1 build. You can click the Release link in the bar on the left to display a list of official releases, including betas. Clicking the link for Axis 1.1 takes you to a page that displays the available files. There’s an Axis binary distribution in a file named axis-1.1.xxx, where .xxx is either .zip or .tar.gz. If you’re using Windows, you’ll probably want to get the zip version of the distribution. UNIX, Linux, and Mac OS X users will probably want to get the .tar.gz version. The source distribution is in a file named axis-1.1-src.xxx, where the values of .xxx are the same as for the binary distribution. You can use a regular archiving utility such as Winzip (on Windows) or GNU tar (on UNIX, Linux, and Mac OS X) to unpack the binary (and source) distribution files. After you do this, you’ll have a directory called axis-1_1 in the current directory (or the directory you specified when unpacking the files).

Here are the important contents of axis-1_1:

docs—Contains all the Axis documentation, including Javadoc.
lib—Contains the jar files needed to use Axis.
samples—The Axis sample applications.
webapps—The sample Axis Web application.
xmls—Ant task files.
LICENSE—The Apache Software License.
README—A basic README (start with docs/index.html).

You need to set up two environments to work with Axis. If you want to write Web service providers, then you need to set up Axis so that it can provide Web services. Doing so typically means installing into a Web container like Tomcat, Jetty, Resin, or the Web container of a J2EE application server. You need this environment to test the services you write.

You also need to set up an environment where you can write the service provider and service requester (client) code. Doing so involves setting your classpath, either on the command line or in your Java development environment. If you’re writing service requestors that need to be deployed in a Web container or EJB container, then you also need the deployment environment we talked about in the last paragraph.

Deployment Environment Setup

We’ll cover setting up an Axis deployment environment using Tomcat. For this example, we assume you’re using Tomcat 4.1.24 as the Web container and JDK 1.4. Axis provides Web services by using a servlet that takes SOAP requests over HTTP and routes them to the appropriate Web services code, performing needed SOAP processing along the way. To set up Axis inside a Web container, you need the relevant Axis jar files, and you need entries in your web.xml file that provide servlet mappings for the Axis servlet. Let’s call the directory where Tomcat is installed CATALINA_HOME, and let’s call the directory where Axis is unpacked AXIS_HOME. We’ll use Windows filename conventions, but you can reverse the slashes for UNIX without any problems.

Follow these steps:

If you’re starting from scratch, then you should copy the directory AXIS_HOME\webapps\axis to CATALINA_HOME\webapps and skip to step 6.
If you have an existing Web application, the process is a little more difficult. You have to copy some files piecemeal from AXIS_HOME to your application. Let’s call the root directory for your Web application (the one inside CATALINA_HOME\webapps) MY_APP.
Copy the jar files from AXIS_HOME\webapps\axis\WEB-INF\lib to MY_APP\WEB-INF\lib.
Copy the JSP file happyaxis.jsp from AXIS_HOME\webapps\axis to MY_APP.
Edit the file MY_APP\WEB_INF\web.xml and copy the <servlet> and <servlet-mapping> elements for AxisServlet and AdminServlet from AXIS_HOME\webapps\axis\WEB-INF\lib. You’ll probably also want to copy the <mime-mapping> elements so your browser knows how to display .wsdl and .xsd files.
Restart Tomcat.
From your Web browser, try to access the happyaxis.jsp file. It’s at the top level of the Web application. If you started from scratch, the URL is http://<server:port>/axis/happyaxis.jsp. If you started with your own Web application, the URL is http://<server:port>/mywebapp /happyaxis.jsp. The happyaxis.jsp attempts to check that all the required Axis libraries are present.
You may want to use Xerces instead of the default JDK 1.4 XML parser. If you decide to do this, follow the directions in Chapter 1 for installing Xerces on JDK 1.4 via the Endorsed Standards Mechanism.

Development Environment Setup

The environment for building Axis service providers and service requestors must contain the same set of jar files you used in step 3 of the previous section:

axis.jar—The main Axis classes.
axis-ant.jar—Ant tasks to make it easier to work with Axis.
commons-discovery.jar—Jakarta library for discovering pluggable interfaces.
commons-logging.jar—Jakarta library for abstracting logging functionality.
jaxrpc.jar—JAX-RPC APIs.
log4j-1.2.8.jar—Jakarta logging library.
saaj.jar—SAAJ APIs.
wsdl4j.jar—WSDL4J (classes for working with WSDL files).

You’ll need to add most of these to your classpath. If you aren’t going to use the Ant tasks, you can leave out axis-ant.jar. Likewise, if you aren’t using the WSDL tools, you can leave out wsdl4j.jar. The easiest way to do this is to define some environment variables to help you. In the following code, replace AXIS_HOME with the value of AXIS_HOME:

set AXIS_LIB=AXIS_HOME\lib set AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\axis-ant.jar;     %AXIS_LIB%\commons-discovery.jar;%AXIS_LIB%\commons-logging.jar;     %AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\log4j-1.2.8.jar;     %AXIS_LIB%\saaj.jar;%AXIS_LIB%\wsdl4j.jar