Assignment 1
Assignment 1 – A Generic Web Service
Compiling, Deploying, and Modifying a Simple Web Service
Version .43 (10 August 2005)
Modifications by James Ruff (Authors: Jeff House and Mark Holliday)
Instructor: Dr. Barry Wilkinson
I. Overview
The purpose for the first assignment is to allow you to familiarize yourself with simple
web services. This assignment will be created using Java SDK 1.5.0 (revision 3) and several
packages from the Apache open source project. This handout will provide you with the steps to
compile and deploy a prewritten web service. Towards the end of the assignment, you will be
required to modify the code that is given to you to help broaden your experience with developing
web services. Grid services are an extension of web services, so understanding web services is
an important first step.
Throughout this document, you will notice that there are several instances of
‘yourusername’. Every time that you encounter this word, please replace it with the
username that you have logged into your particular server with.
II. Basic Linux Terminology and Usage
This assignment will require the use of the Linux operating system. Although the
commands are similar to the commands from the Microsoft Windows command prompt, there
are several important differences. These differences are described in the sections that follow.
Where appropriate, there will be examples of Microsoft Windows commands with the respective
Linux commands.
First Difference – Remote Connection
Many Microsoft Windows users are familiar with the idea of using a remote desktop
connection. This technology is not new. It is probable that you will not be able to be in front of
the computer that you are going to be using. Thus, you will need software to make a secure
connection. Both Microsoft and Linux distributions have options to connect securely. If you are
using Linux to connect to these remote computers, no additional software needs to be
downloaded and installed. Microsoft Windows users should use a free program called PuTTY.
(http://www.chiark.greenend.org.uk/~sgtatham/putty/) This program, once
downloaded, can provide telnet, ssh, and remote connections. In order to connect to the
machine, download a copy of PuTTY to your desktop. To load PuTTY, double click on the
newly created icon. This will bring up a box that contains all of the connection information. The
first box will be a hostname field. Once you have typed the hostname in the hostname field, you
must select what kind of connection to follow. Selecting the radio button for SSH will cause the
number '22' to be placed in the port field. Once this task is completed, you may hit <enter> to
start the session.
Linux users, on the other hand, may use a single command from the command terminal to
initiate a SSH transaction. This command would be “ssh”. An example command would be:
ssh foo@bar.com where 'foo' is the user name and 'bar.com' is the host.
1 of 11
Assignment 1
The PuTTY user will be asked to enter in the user name for that particular server. Both
the Linux and PuTTY user will be asked for the password for the server. Once this is completed,
you will have a command line connection to the server in question.
Command Line Functions
The command line is a powerful tool in the Linux operating system. A brief list of
commands will be provided below. If you have any questions about any of the commands
provided below, just enter in 'man <space> <command name>' to view the manual page
for the command.
 cd <directory location> - (Same for both Windows and Linux) – Moves you to a
particular directory on the system. For example 'cd /tmp' will take you to the /tmp
directory of the system.
 pwd – (No Microsoft Windows equivalent) – Prints out the current directory that you are
located within.
 ls – (Same as dir from Microsoft Windows) – Prints out everything that is in the current
directory.
 cp <from> <to> - (copy <from> <to> in Microsoft Windows) – Copies a file from
one location on the system to another.
 rm <file> - (del <file> from Microsoft Windows) – Removes a file from the system.
(Add the flags –rf in Linux ONLY) to remove entire directories.
 mkdir <directory_name> - (Same for both Windows and Linux) – Creates a new
directory on the system.
 touch <filename> - (No equivalent in Windows) – Creates an empty file.
III. Creating a web service
Specifics:
We will:
 Prepare the directory structure.
 Create the web service source code as a jws (Java web service) file.
 Generate several Java source files representing the service from that jws file using the
Axis tool.
 Compile the files created in the previous step.
 Create client source and compile.
 Execute client to access the service.
 Extend the service by adding functionality.
The web service for this assignment is a simple math service that can perform an arithmetic
operation (returning the square of its argument) for a client. The math service itself is not
stateful, meaning that the result of any previous arithmetic operation is not remembered by the
service.
Step 1 - Preparation of Directory Structure
Once you have logged into the server you will be using for this assignment, create a
2 of 11
Assignment 1
directory in your home directory called “WebServices” using the command “mkdir
WebServices”:
[yourusername@someserver yourusername]$ mkdir WebServices
[yourusername@someserver yourusername]$ ls
WebServices
We use the 'ls' command to verify that the directory has been created. Once you are sure the
directory has been created, move into that directory by using the command 'cd
WebServices':
[yourusername@someserver yourusername]$ cd WebServices
[yourusername@someserver WebServices]$
Step 2 – Defining the service with Java
The first step is to write the code that will be the actual service. This service does not
have to be very complicated or any special code. For this assignment, we will be using a class
called “MyMath” which resides in the file “MyMath.jws”. Using your favorite text editor,
type in this class and save it into the correct file:
public class MyMath
{
public int squared( int x ) {
return x * x;
}
}
Once this task has been completed, we must now place the file where Apache Axis can find the
file. Each user has been created a special account that only they can write to. This directory is
located in “$CATALINA_HOME/webapps/axis/yourusername/”. $CATALINA_HOME
is the environment variable specifying the path to the home directory of the Apache Tomcat java
servlet container.
Copy your “MyMath.jws” file to the
“$CATALINA_HOME/webapps/axis/yourusername/” directory by using the following
command:
[yourusername@someserver WebServices]$ cp MyMath.jws \
$CATALINA_HOME/webapps/axis/yourusername/
*We will be using the '\' character to let the terminal know that the line of text continues on the
next line.
You can now surf the web to find your newly deployed web service. If you point your web
3 of 11
Assignment 1
browser to the following url, you will be able to see how your service is deployed.
(http://yourserver.yourdomain.edu:8080/axis/yourusername/) This
should bring up a window that looks similar to the following:
Notice that you now have a “MyMath.jws” available as a link. Click on this link to get the
following window:
Even though we can connect to the service from a web browser, we are unable to have another
client access and use the service. The next step of the assignment will go through the steps of
allowing a client to connect to the service and how to write the client that will access the service.
Step 3 - Create the Java source files needed for a web service
The second step defines an interface for the service that a client can use to access the
service. The interface is defined using the Web Service Description Language (WSDL),
http://www.w3.org/TR/wsdl, which specifies that operations are exposed through the
web service clients. Axis (http://ws.apache.org/axis/) is an implementation of the
Simple Object Access Protocol (SOAP). Use Axis tool WSDL2Java to generate the Java source
files needed by a client to access the web service from the MyMath.jws file that you created in
step one. There are two approaches to creating the WSDL and interface classes. This
assignment handout will show both, starting with the more difficult one.
Approach One: Use Two Commands
The first way to create the interfaces and WSDL file is to use two tools that come with Apache
Axis.
Substep 3.1: Use Java2WSDL
The first tool is Java2WSDL. The Java2WSDL tool creates a “WSDL document [that] will
contain the appropriate WSDL types, messages, portType, bindings and service descriptions to
4 of 11
Assignment 1
support a SOAP rpc, encoding web service.1” In order to use this tool, you must define a class,
MyMath.java, that contains the same contents as the MyMath.jws file.
[yourusername@someserver WebServices]$ cp MyMath.jws MyMath.java
Compile the class by typing the following command:
[yourusername@someserver WebServices]$ javac MyMath.java
We can now generate the WSDL file from the Java interface. To do this, run the following
command:
[yourusername@someserver WebServices]$ java \
org.apache.axis.wsdl.Java2WSDL -o MyMath.wsdl \
-l"http://localhost:8080/axis/yourusername/MyMath" MyMath
The arguments to this command are quite important.



The ‘org.apache.axis.wsdl.Java2WSDL’ argument gives the package information
on where to find the Java2WSDL class.
The ‘-o MyMath.wsdl’ argument gives the filename of the output WSDL file.
The ‘-l”http://localhost:8080/axis/yourusername/MyMath”' argument
gives the location of the service in question.
The output of this command is a single WSDL file called ‘MyMath.wsdl’. The complete
WSDL file is provided below:
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://DefaultNamespace"
xmlns:apachesoap="http://xml.apache.org/xml-soap"
xmlns:impl="http://DefaultNamespace" xmlns:intf="http://DefaultNamespace"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!--WSDL created by Apache Axis version: 1.2
Built on May 03, 2005 (02:20:24 EDT)-->
<wsdl:message name="squaredRequest">
<wsdl:part name="in0" type="xsd:int"/>
</wsdl:message>
<wsdl:message name="squaredResponse">
<wsdl:part name="squaredReturn" type="xsd:int"/>
1
http://ws.apache.org/axis/java/user-guide.html#Java2WSDLBuildingWSDLFromJava
5 of 11
Assignment 1
</wsdl:message>
<wsdl:portType name="MyMath">
<wsdl:operation name="squared" parameterOrder="in0">
<wsdl:input message="impl:squaredRequest" name="squaredRequest"/>
<wsdl:output message="impl:squaredResponse" name="squaredResponse"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="MyMathSoapBinding" type="impl:MyMath">
<wsdlsoap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/h
ttp"/>
<wsdl:operation name="squared">
<wsdlsoap:operation soapAction=""/>
<wsdl:input name="squaredRequest">
<wsdlsoap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encodi
ng/" namespace="http://DefaultNamespace" use="encoded"/>
</wsdl:input>
<wsdl:output name="squaredResponse">
<wsdlsoap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encodi
ng/" namespace="http://DefaultNamespace" use="encoded"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="MyMathService">
<wsdl:port binding="impl:MyMathSoapBinding" name="MyMath">
<wsdlsoap:address
location="http://localhost:8080/axis/testaccount/MyMa
th"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
6 of 11
Assignment 1
Substep 3.2: Use WSDL2Java
With the WSDL file created, you can now type the following command to generate the Java
source files required for the client:
[yourusername@someserver WebServices]$ java \
org.apache.axis.wsdl.WSDL2Java -o . -d Session -s -S true \
-p localhost.axis.yourusername.MyMath_jws MyMath.wsdl
The arguments are very important for this command as well.
 The ‘org.apache.axis.wsdl.WSDL2Java’ argument defines which package the
WSDL2Java class resides in.
 The ‘-o’ argument specifies that the output files should be placed in the current directory.
 The ‘-s S true’ argument specifies that the server side bindings and the skeleton should
be deployed.
 The ‘-d Session’ argument specifies that the build should be done on a ‘Session’ basis.
 The ‘-p localhost.axis.yourusername.MyMath_jws’ argument specifies the
package the classes and stubs should be placed in. This command outputs several files which
will be described later in this section.
Approach Two: Use One Command
The second way to create the interfaces and WSDL file involves only one command from the
command line. This change in the command is syntactic sugar for the previous steps we have
already completed. This method is shown as an option to the previous two substeps. While you
are still in the directory '/home/yourusername/WebServices/', you can run the
automatic generation function by typing the following command:
[yourusername@someserver WebServices]$ java -classpath \
$AXISCLASSPATH org.apache.axis.wsdl.WSDL2Java \
http://localhost:8080/axis/yourusername/MyMath.jws?wsdl
The WSDL2Java program will locate the MyMath.jws file and will create all of the needed
Java source files. The second argument of the command is a URL (Universal Resource
Location) specifying the web server that is listening on TCP port 8080 on the local machine.
The port number for your particular server may be different than this. If you receive an error
message about the port information, please contact your system administrator.
The result of executing the WSDL2Java program is a directory inside of
'/home/yourusername/WebServices/' called 'localhost'. You can use the ‘ls’
command to view this. The 'localhost' directory has a subdirectory named 'axis' which has
another subdirectory named 'yourusername' which has a subdirectory named 'MyMath_jws'.
This series of directories was created because it follows the parts of the URL provided above.
The directory 'MyMath_jws' has four files within it:
7 of 11
Assignment 1




MyMath.java: source for the Java interface for MyMath class.
MyMathService.java: source for the Java interface that includes the getMyMath
method specification.
MyMathServiceLocator.java: source for the Java class
MyMathServiceLocator.
MyMathSoapBindingStub.java: source for the Java class
MyMathSoapBindingStub.
These files are the Java source files created by WSDL2Java and are needed to make MyMath’s
client. The command invoking WSDL2Java could have instead been written as:
[yourusername@someserver WebServices]$ java -classpath \
$AXISCLASSPATH org.apache.axis.wsdl.WSDL2Java \
http://yourserver.yourdomain.edu:8080/axis/yourusername/MyMath.j
ws?wsdl
The difference is that the Fully Qualified Domain Name of the current machine,
yourserver.yourdomain.edu, is being used instead of the term localhost. The only
difference in the output is that the directory created in the current directory is not named
'localhost'. Instead, you get a directory called 'edu' which has a subdirectory 'wcu' (if your
machine is at WCU), and so forth.
Step 4 – Compile Java Source Files Just Generated
While you are still in the directory '/home/yourusername/WebServices' compile
the four Java source files generated by the previous step with the command:
[yourusername@someserver WebServices]$ javac -classpath \
$AXISCLASSPATH:$CLASSPATH \
localhost/axis/yourusername/MyMath_jws/*.java
or the command
[yourusername@someserver WebServices]$ javac -classpath \
$AXISCLASSPATH:$CLASSPATH \
edu/yourdomain/yourserver/yourusername/MyMath_jws/*.java
depending on how you invoked the WSDL2Java command as described earlier.
Step 5 - Write the Client Source
While you are still in the directory '/home/yourusername/WebServices/' create
a file named 'MyMathClient.java' that contains the code for the client. The client source
code that you are to place in the 'MyMathClient.java' file is given below. The import
statements will assume that you invoked the WSDL2Java program using localhost, not
8 of 11
Assignment 1
yourserver.yourdomain.edu.
// Required for Axis 1.1:
import localhost.axis.yourusername.MyMath_jws.MyMathServiceLocator;
import localhost.axis.yourusername.MyMath_jws.MyMathService;
import localhost.axis.yourusername.MyMath_jws.MyMath;
import org.apache.axis.client.*;
// Axis 1.1
import
import
import
import
org.apache.axis.encoding.XMLType;
org.apache.axis.utils.Options;
java.net.*;
javax.xml.rpc.ParameterMode;
//
//
//
//
Required
Required
Required
Required
as of Axis 1.2
as of Axis 1.2
for URL
as of Axis 1.2
public class MyMathClient {
public static void main(String args[]) throws Exception {
MyMathService service = new MyMathServiceLocator(); // locate the service
Integer x = new Integer(args[1]); // Take the command line parameter
// and generate an Integer object.
Options options = new Options( args );
// Passing arguments. Required
// for getPort command.
String endpoint = "http://localhost:" + options.getPort() +
"/axis/yourusername/MyMath.jws"; // Tell the class where to
// look for service.
Call call = (Call) service.createCall(); // Designate that a call will
// be made.
call.setTargetEndpointAddress( new URL( endpoint ) ); // designate the
// target service
call.setOperationName( "squared" ); // the method name of the service
// define the parameters that the method requires.
call.addParameter( "op1" , XMLType.XSD_INT, ParameterMode.IN);
// define the parameters that the method returns.
call.addParameter( "op2" , XMLType.XSD_INT , ParameterMode.OUT );
// Set the return type of the call. (Required because of addParameter.)
call.setReturnType( XMLType.XSD_INT );
// Hold the result of the method call and make the call. (Invoke must
// always have an array of objects passed to it.)
int ret = (Integer) call.invoke( new Object[] { x } );
// Show the result:
System.out.println( "The square of “ + x + “ is “ + ret );
}
}
This client exercises the service by calling it to compute and return the square of the number
passed as an argument.
Step 6 – Compile Client Code
While you are still in the directory '/home/yourusername/WebServices/'
compile the client code with:
9 of 11
Assignment 1
[yourusername@someserver WebServices]$ javac -classpath \
$AXISCLASSPATH:$CLASSPATH:. MyMathClient.java
Be careful to ensure there is at least one space before the argument 'MyMathClient.java'
to separate it from the previous argument. The previous argument,
'$AXISCLASSPATH:$CLASSPATH:.' has the ':.' at the end of it to force the Java compiler
to look at the current directory.
Step 7 – Execute web service Program
While you are still in the directory '/home/yourusername/WebServices/'
execute the client code with:
[yourusername@someserver WebServices]$ java -classpath \
$AXISCLASSPATH:$CLASSPATH:. MyMathClient –p8080 4
The argument ‘-p8080’ tells the client which port to work with. There should not be a space
between ‘-p’ and ‘8080’.
You should get the following output:
The square of 4 is 16
Step 8 – Add Functionality to the Web Service Program
In this step you are to extend the service by adding the following two methods. You also
must extend the client to test the new methods.

The method named isPrime returns a Boolean object with the value of true if and only
if the integer argument passed to it is a prime number. (For more information about prime
numbers, please visit
http://mathworld.wolfram.com/PrimeNumber.html.)

The method named isEven that returns a Boolean object with the value of true if and
only if the integer argument passed to it is even.
(http://mathworld.wolfram.com/EvenNumber.html)
To do this, the basic idea is to repeat the first six steps above but adding in the extra code in the
'MyMath.jws' and 'MyMathClient.java' files. All the steps are to be done while you are
in the directory '/home/yourusername/WebServices/'.
Appendix A: Additional Resources
Apache web services Project: http://ws.apache.org/
10 of 11
Assignment 1
Apache Axis: http://ws.apache.org/axis
Apache ANT: http://ant.apache.org
Apache Tomcat: http://jakarta.apache.org
Web Service Description Language: http://www.w3.org/TR/wsdl
On To Java – Axis web services: http://www.onjava.com/lpt/a/1578
Appendix B: PuTTY Installation
PuTTY is available for download (for free) from
http://www.chiark.greenend.org.uk/~sgtatham/putty. To install the
software, go to the 'Download' page and click 'putty.exe'. Once this is done, select “SAVE”
and save it to the desktop. Once this is completed, you have successfully installed PuTTY on
your computer.
Acknowledgement
This assignment is derived from “Classroom Exercises for Grid Services” by A. Apon, J. Mache,
Y. Yara, and K. Landrus, Proc. 5th Int. Conference on Linux Clusters: The HPC Revolution May
2004.
11 of 11