Installing Apache Axis

Important Note: The following instructions assume that you are using an account on csci571.usc.edu. If you are running on a different host, csci571b.usc.edu for example, you must replace the hostname accordingly in all commands that refer to hostnames. 

 Install Apache Axis

Download the binary package axis-1_1.tar from

http://www-scf.usc.edu/~csci571/download/axis-1_1.tar

Place it in home directory. Use the following command to unpack the tar file:

gtar xvf axis-1_1.tar

You should delete axis-1_1.tar, which is no longer needed.

Notes:  You should use the GNU version of the tar program, gtar. The Solaris version of tar evidently has some bug in it that makes it not work with some tar files. The tar program creates a directory axis-1_1.

Alternative download: since we need only a small part of the Axis distribution, you can alternatively download just the “webapps” portion of Axis (needed by Tomcat) from:

http://www-scf.usc.edu/~csci571/download/axis_webapps.tar

Expand the tar file into $CATALINA_HOME/webapps. After this step $CATALINA_HOME/webapps should contain the directory ‘axis’. In other words, the content of

$CATALINA_HOME/webapps/axis

should be the same as:

~/axis-1_1/webapps/axis

of the “full” Axis distribution. If you have downloaded the full distribution you should 'move' the entire content of the Axis 'webapp' directory to Tomcat's webapp directory, as in:

mv ~/axis-1_1/webapps/axis $CATALINA_HOME/webapps

 Configuring Axis for Jakarta Tomcat

Copy jaxrpc.jar and saaj.jar from $CATALINA_HOME/webapps/axis/WEB-INF/lib to $CATALINA_HOME/common/lib.

Restart Apache Tomcat. To verify for a correct installation, visit the Axis webapp. You can do this by visiting the following URL:

http://csci571.usc.edu:port#/axis

Where “port#” is your Tomcat port number. Click on the “Validate” link. This should indicate that all the required components were found and one component, related to security, is missing (this is fine).

If you get a message that “activation.jar” is missing, download the file from here and place it in your Tomcat common/lib directory. Stop Tomcat, restart it and validate again.

Test the preinstalled web service “version” by visiting the URL:

http://csci571.usc.edu:port#/axis/services/Version?method=GetVersion

If the URL works you will get back an XML file which represents a SOAP envelope. The envelope defines the response, named GetVersionResponse, to an operation whose name is GetVersion. The value returned by the response, named GetVersionReturn, is the string "Apache Axis version: 1.1 Built on June 13, 2003"

Test the preinstalled web service “echoHeaders” by visiting the URL:

http://csci571.usc.edu:port#/axis/EchoHeaders.jws?method=list

If the URL works you will get back an XML file which represents a SOAP envelope. The envelope defines the response, named listResponse, to an operation whole name is list. The value returned by the response, named listReturn, is the set of headers that are sent from the browser.

Important Note: There is an incompatibility between Java version 1.4.1 and Axis JWS file support. You should make sure that you are using Java version 1.4.0, such as 1.4.0_01-b03, which we know is compatible. If you try to invoke EchoHeaders.jws as shown above with Java version 1.4.1, the IE browser will report an "error 500 - Internal Server Error".

If you get reasonable XML responses from the web service tests, then your axis install was successful. Look at the Axis installation document, for more information.

Adding Axis “jar” files to the CLASSPATH

Axis development will require you to add the Axis “jar” files to the Java CLASSPATH. The following jar files need to be in the CLASSPATH:

axis.jar, commons-logging.jar, commons-discovery.jar, wsdl4j.jar, jaxrpc.jar, saaj.jar (from Axis)

You also need to have '.' in the CLASSPATH, too.

To accomplish this, add these lines to the .cshrc file in your home directory:

setenv AXIS_HOME ${CATALINA_HOME}/webapps/axis

setenv AXIS_LIB ${AXIS_HOME}/WEB-INF/lib

setenv AXIS_CLASSPATH ${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}/wsdl4j.jar

(Important Note: The last line should be entered as a single line, WITHOUT CARRIAGE RETURNS; the hyphens after "commons" should be included)

if ( ${?CLASSPATH} ) then
  setenv CLASSPATH .:${AXIS_CLASSPATH}:${CLASSPATH}
else
  setenv CLASSPATH .:${AXIS_CLASSPATH}
endif

You now have all the needed libraries for Axis Web Services development. To make sure your typing has been done correctly, execute:

source .cshrc

You should receive no errors.

Test Creation of a Web Service (jws method)

Important Note: This remaining tests in this installation (including setting up SOAPMonitor), while not specifically required by any of the homework exercises, will give you a full understanding of the capability of the Axis Web Services engine. However, you will have to use WSDL2Java for the homework exercises, and these tests will help you in understanding that process. It is recommended that you review the material related to Web Services, and WSDL in particular, prior to performing these tests.

There are several ways to create Web Service in Axis. We take a look at the simple method here. In this approach we create a simple java file with some public methods. We will copy this file to the directory $CATALINA_HOME/webapps/axis/, with the extension .jws (Java Web Service) instead of .java.

If your java file is called Calculator.java the target will be $CATALINA_HOME/webapps/axis/Calculator.jws.

Let's create a simple class, named Calculator, and store it in the file Calculator.java, like the following one:

public class Calculator {
   public int add(int i1, int i2)
   {
     return i1 + i2;
   }

   public int subtract(int i1, int i2)
   {
     return i1 - i2;
   }
}

Note: You'll find this very class in axis-1.1/samples/userguide/example2/Calculator.java which is included with the full Axis distribution. The "webapps" portion of Axis does not include this file.

Copy the above Java file into your $CATALINA_HOME/webapps/axis directory, and rename it Calculator.jws. So you might do something like this:

$ cp Calculator.java $CATALINA_HOME/webapps/axis/Calculator.jws

You should now be able to access the service WSDL at the following URL:

http://csci571.usc.edu:port#/axis/Calculator.jws?WSDL

Axis automatically locates the file, compiles the class on the fly, and dynamically creates teh WSDL for addition and subtraction operations. When invoked Axis will convert SOAP calls correctly into Java invocations of your service class. It will take some time to load the server the first time (as much as 1 minute). A Calculator client is in samples/userguide/example2/CalcClient.java. See the Axis User Guide for more information on JWS files.

Test Creation of a Web Service (WSDL method)

While web services may be called without using a WSDL, as shown above, we will use a WSDL file to create client side stubs and use these stubs to make our WS client. To generate the client side stubs we use the tool WSDL2Java. This tool is included in the jar file axis.jar, so it must be in your CLASSPATH to in order to invoke this tool. If you have set up the CLASSPATH as above, you can invoke WSDL2Java as follows, from the "webapps/axis" subdirectory :

UNIX:
java -classpath $CLASSPATH org.apache.axis.wsdl.WSDL2Java http://csci571.usc.edu:port#/axis/Calculator.jws\?WSDL

Windows:
java -classpath %CLASSPATH% org.apache.axis.wsdl.WSDL2Java http://localhost:port#/axis/Calculator.jws?WSDL

(Important Note: the above command should be typed in a single line, WITHOUT CARRIAGE RETURNS. Substitute the appropriate host and port#.)

In UNIX, this command if successful will generate the following files:

edu/usc/csci571/axis/Calculator_jws/Calculator.java
edu/usc/csci571/axis/Calculator_jws/CalculatorService.java
edu/usc/csci571/axis/Calculator_jws/CalculatorServiceLocator.java
edu/usc/csci571/axis/Calculator_jws/CalculatorSoapBindingStub.java

In Windows, the same files will be created in the subdirectory localhost\axis\Calculator_jws.

The generated code implements the following functionality:

Calculator.java - The is the "remote" interface. Eextends Remote and includes methods from the original Calculator.java.
CalculatorService.java - Service interface of the Werb Services. The ServiceLocator implements this interface.
CalculatorServiceLocator.java - Helper factory for retrieving a handle to the service.
CalculatorSoapBindingStub.java - Client-side stub code that encapsulates client access.

Now we need to write a Client that uses these stubs to make a SOAP call. Here is an example client, Client.java. Save this program in the same directory where the stubs are located: edu/usc/csci571/axis/Calculator_jws (UNIX) or localhost\axis\Calculator_jws (Windows).

// UNIX:
package edu.usc.csci571.axis.Calculator_jws;
// Windows: 
// package localhost.axis.Calculator_jws;

public class Client
{
   public static void main(String args[])
   {
      Client c = new Client();
      try
      {
          c.foo();
      }
      catch(Exception e)
      {
          System.out.println(e);
      }
   }

   void foo() throws Exception
   {
      CalculatorService cs = new CalculatorServiceLocator();
      Calculator port = cs.getCalculator();
      System.out.println("The sum of 2 and 3 is " + port.add(2,3));
      System.out.println("The diff of 2 and 3 is " + port.subtract(2,3));
   }

}

Important Note: All of the following compilations and client execution must be performed from the "main" axis directory. Executing them from any other directory will result in compilation and execution errors, such as "Exception in thread "main" java.lang.NoClassDefFoundError".

In UNIX, compile the stubs as follows, from the webapps/axis directory:

javac –classpath $CLASSPATH edu/usc/csci571/axis/Calculator_jws/Calculator.java
javac –classpath $CLASSPATH edu/usc/csci571/axis/Calculator_jws/CalculatorService.java
javac –classpath $CLASSPATH edu/usc/csci571/axis/Calculator_jws/CalculatorServiceLocator.java
javac –classpath $CLASSPATH edu/usc/csci571/axis/Calculator_jws/CalculatorSoapBindingStub.java

In Windows, compile the stubs as follows, from the webapps/axis directory:

javac -classpath %CLASSPATH% localhost/axis/Calculator_jws/Calculator.java 
javac -classpath %CLASSPATH% localhost/axis/Calculator_jws/CalculatorService.java
javac -classpath %CLASSPATH% localhost/axis/Calculator_jws/CalculatorServiceLocator.java
javac -classpath %CLASSPATH% localhost/axis/Calculator_jws/CalculatorSoapBindingStub.java

Compile the client as follows, from the webapps/axis directory:

UNIX:
javac –classpath $CLASSPATH edu/usc/csci571/axis/Calculator_jws/Client.java
Windows:
javac -classpath %CLASSPATH% localhost/axis/Calculator_jws/Client.java

Run the client as follows, from the webapps/axis directory:

UNIX:
java –classpath $CLASSPATH edu/usc/csci571/axis/Calculator_jws/Client
Windows:
java -classpath %CLASSPATH% localhost/axis/Calculator_jws/Client

If the client if successful running the WSDL-based service, it will print the following two lines:

The sum of 2 and 3 is 5
The diff of 2 and 3 is -1 

Enabling SOAPMonitor in Axis

All the SOAPMonitor code is present in the Axis 1.1 release, but the applet itself was not compiled and the service may not be not enabled in the distribution. Here are the steps to enable the SOAPMonitor service for Axis running under Tomcat.

1. Go to the Tomcat webapps/axis directory, and compile the applet with:

javac -classpath WEB-INF/lib/axis.jar SOAPMonitorApplet.java 

2. Create the SOAPMonitorService Deployment Descriptor: save this code in a file named deploy-monitor.wsdd in the axis directory:

<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>

3. Now deploy the service by running the admin client with deploy-monitor.wsdd. Execute the following command from the axis directory. If you are not in this directory you will get a "java.io.FileNotFoundException: deploy-monitor.wsdd (The system cannot find the file specified)" exception.

java -cp $AXIS_CLASSPATH org.apache.axis.client.AdminClient -lhttp://localhost:port#/axis/services/AdminService deploy-monitor.wsdd

If you get some java client error (like ClassNotFoundException), then you haven't set up your AXIS_CLASSPATH (or CLASSPATH) variable right, mistyped the classname, or did some other standard error. Tracking down such problems are foundational Java development skills.

Note: You may need to replace localhost with your host name, and port# with the port number used by your web server.

4. Enable the SOAPMonitor Service. On some Axis ditributions, SOAPMonitor is disabled by default. To enable it, you need to modify the Axis startup file at axis/WEB-INF/web.xml. You will need to make sure that the following lines are not commented out (as they may be by default):

  <servlet>
    <servlet-name>SOAPMonitorService</servlet-name>
    <display-name>SOAPMonitorService</display-name>
    <servlet-class>
        org.apache.axis.monitor.SOAPMonitorService
    </servlet-class>
    <init-param>
      <param-name>SOAPMonitorPort</param-name>
      <param-value>5001</param-value>
    </init-param>
    <load-on-startup>100</load-on-startup>
  </servlet>
.....
  <servlet-mapping>
    <servlet-name>SOAPMonitorService</servlet-name>
    <url-pattern>/SOAPMonitor</url-pattern>
  </servlet-mapping>

Remove the comment lines (<!-- and -->) around this code.

Important Note: you may also have to the change the port used by SOAPMonitor from port 5001 (see above in bold) to a different port #, to avoid conflicts with other users of SOAPMonitor running on the same machine. After you do this you will have to shutdown Tomcat and restart it.

5. Point a browser at http://localhost:port#/axis/SOAPMonitor to bring up the viewer applet.

6. Enable application for Monitoring. You will have to modify the deployment descriptor deploy.wsdd to allow monitoring. See below for an example on how to do this with the "fibonacci" example from Dion Almaer article.

<service name="fibonacci" provider="java:RPC" style="rpc" use="encoded">
<!-- added for SOAPMonitor -->>
    <requestFlow>
      <handler type="soapmonitor"/>
    </requestFlow>
    <responseFlow>
      <handler type="soapmonitor"/>
    </responseFlow>

% java org.apache.axis.client.AdminClient -p port# undeploy.wsdd
<admin>Done processing</admin>

% java org.apache.axis.client.AdminClient -p port# deploy.wsdd
<admin>Done processing</admin>