Web Services Homework Exercise

Objective

The objective of this exercise is to gain experience programming Web Services, to be able to describe the purpose of the technologies underlying Web Services, and to understand how these technologies are used in Web Services. 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.

Prerequisites

  1. This exercise assumes that you have some preliminary experience with Java. If you have never programmed in Java then you should spend some time going through the tutorial on Learning the Java Language at http://java.sun.com/docs/books/tutorial/java.

  2. This exercise also assumes that you have had exposure to some basic Internet concepts. Some helpful references for this are at:

Overview

The steps of this exercise are:

  1. Read some preparation material on Web Services
  2. Create Web service source code as a jws (Java Web Service) file
  3. Generate several Java source files representing the service from that jws file using the Axis tool
  4. Compile the files created in the previous step
  5. Create the client source
  6. Compile the client source
  7. Execute the client to access the service.
  8. Extend the service by adding functionality
  9. Answer the post-exercise questions.
What to turn in: The code for your assignment should be in your account on talon, in a subdirectory entitled "WebServices". I will grade your assignment by executing your code from talon. Turn in the answers to the questions on paper to me in class.

STEP 0: Preparation

To get some basic background in the concepts of Web Services, read the first five sections of "Introduction to Web services and the WSDK V5.1" from IBM at https://www6.software.ibm.com/developerworks/education/ws-intwsdk51/index.html. Access to the tutorial is free, although you will need to register. We will not use the WSDK for this exercise, but rather will use tools that are on the Linux machine, talon. So, you can stop reading when you get to the section on "Setting up the WSDK" unless you are interested in reading further on your own.

STEP 1: Define the Service with Java

In your home directory on talon, create a subdirectory entitled WebServices. Assuming that you are in your home directory, execute "cd WebServices" to change to this directory. Use your favorite editor to create a file named MyMath.jws (Java Web Service) in the current directory. The file MyMath.jws contains the Java code that implements the Math Service. Type the following Java code into the MyMath.jws file: 

public class MyMath 
{
  public int squared(int x) 
  {
    return x * x;
  }			
}

Part of the Apache open source project is support for web services, http://ws.apache.org/. That support includes the Axis tool, http://ws.apache.org/axis/. Axis is an implementation of the Simple Object Access Protocol (SOAP) which is a key protocol in web services. As part of supporting SOAP Axis includes a program called WSDL2Java that will accept a Java source file that contains a Java class that implements a service and will generate the Java source files needed to make that Java class into a web service. The input Java source file must have the extension jws to indicate that the Java source is intended to be a Java Web Service.

Axis expects the jws file to be in one of several standard locations. To support that requirement we have created another directory for you that is at $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. You can see the value of this environment variable by using the following command. 

[yourusername@talon WebServices]$ printenv CATALINA_HOME
/usr/local/jakarta-tomcat-5.0.25
[yourusername@talon WebServices]$

You can see the directory that has been created for you and that it is currently empty by the following command. 

[yourusername@talon WebServices]$ ls $CATALINA_HOME/webapps/axis/yourusername/
[yourusername@talon WebServices]$
Copy the jws file to the directory we just listed so that Axis will be able to find the file. Copy the file with the following command. 

[yourusername@talon WebServices]$cp MyMath.jws   \
$CATALINA_HOME/webapps/axis/yourusername/

The backspace character is because the command is on more than one line. Each backspace character must immediately precede a newline character. You can see that the file has been copied by doing the following command. 

[yourusername@talon WebServices]$ ls $CATALINA_HOME/webapps/axis/yourusername/
MyMath.jws
[yourusername@talon WebServices]$

STEP 2: Create the Java source files needed for a web service

The second step in developing a Web Service is defining the interface for the service. The interface is defined using the Web Service Description Language (WSDL), http://www.w3.org/TR/wsdl, which specifies what operations are exposed through the Web Service to 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 to implement a web service from the MyMath.jws file that you created in step one. While you are still in the directory /home/yourusername/WebServices/ this automatic generation is done with the command: 

[yourusername@talon WebServices]$ java -classpath     \
$AXISCLASSPATH org.apache.axis.wsdl.WSDL2Java      \
http://localhost:8080/axis/yourusername/MyMath.jws?wsdl

The command is shown on two lines, but all commands must be entered all on one line unless the newline character is escaped by the backslash character, "\". The Axis WSDL2Java program finds the MyMath.jws file and creates the needed Java source files. The second argument is a URL (Universal Resource Location) specifying the web server that is listening on TCP port 8080 on the local machine. On talon the Apache tomcat web server is running and listening on that port.

The result of executing the WSDL2Java program is to create in the current directory, /home/yourusername/WebServices, a directory named localhost. You can use the ls command to see this. The localhost directory has a subdirectory named axis which has a subdirectory named yourusername which has a subdirectory named MyMath_jws. This series of directories was created because it follows the parts of the URL http://localhost:8080/axis/yourusername/MyMath.jws?wsdl. The directory MyMath_jws that has four files in it.

These files are the Java source files created by WSDL2Java and are needed to make MyMath into a web service. The command invoking WSDL2Java could instead have been written as: 

[yourusername@talon WebServices]$ java -classpath $AXISCLASSPATH    \
org.apache.axis.wsdl.WSDL2Java      \
http://talon.csce.uark.edu:8080/axis/yourusername/MyMath.jws?wsdl
The backspace characters are because the command is on more than one line. Each backspace character must immediately precede a newline character. The difference is that the Fully Qualified Domain Name of the current machine, talon.csce.uark.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 it is named edu and has a subdirectory name wcu that has a subdirectory named cs that has a subdirectory named talon. The subdirectory named talon has a subdirectory named axis just as the subdirectory named localhost has a subdirectory named axis.

STEP 3: Compile Java Source Files Just Generated

While you are still in the directory /home/yourusername/WebServices/ compile the four Java source files generated by step two with the command: 

[yourusername@talon WebServices]$ javac -classpath $AXISCLASSPATH   \
localhost/axis/yourusername/MyMath_jws/*.java

or the command 

[yourusername@talon WebServices]$ javac -classpath $AXISCLASSPATH \
edu/uark/csce/talon/axis/yourusername/MyMath_jws/*.java
depending on how you invoked the WSDL2Java command as described above. The backspace character is because the command is on more than one line. Each backspace character must immediately precede a newline character.

STEP 4: Write 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 file MyMathClient.java is given below. The three import statements assume that you invoked the WSDL2Java program using localhost, not talon.csce.uark.edu. 

import localhost.axis.yourusername.MyMath_jws.MyMathServiceLocator;
import localhost.axis.yourusername.MyMath_jws.MyMathService;
import localhost.axis.yourusername.MyMath_jws.MyMath;

public class MyMathClient {
public static void main(String args[]) throws 
	Exception {
    MyMathService service = new MyMathServiceLocator();
    MyMath myMath = service.getMyMath();
    int x = (new Integer(args[0])).intValue();
    System.out.println("The square of " + args[0] + 
" is " + myMath.squared(x));
  }
}

This client exercises the service by calling it to compute and return the square of the number passed as an argument.

STEP 5: Compile Client Code

While you are still in the directory /home/yourusername/WebServices/ compile the client code with: 

[yourusername@talon WebServices]$ javac -classpath $AXISCLASSPATH:.  \
MyMathClient.java
The backspace character is because the command is on more than one line. Each backspace character must immediately precede a newline character. 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:., has the :. at the end to force the java compiler to look at the current directory.

STEP 6: Execute Web Service Program

While you are still in the directory /home/yourusername/WebServices/ execute client code with: 

[yourusername@talon WebServices]$ java    -classpath    $AXISCLASSPATH:.  \
MyMathClient       4
The backspace character is there because the command is on more than one line. Each backspace character must immediately precede a newline character. Be careful to ensure there is at least one space before and after the argument MyMathClient to separate it from the previous and following arguments. You should get the following output: 

The square of 4 is 16

STEP 7: Add Functionality to the Web Service Program

In this step you are to extend the service by adding additional functionality. In particular you are to add a method named IsEven that returns true if the integer argument passed to it is an even number and false otherwise. To do this, the basic idea is to repeat 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 still in the directory /home/yourusername/WebServices/

STEP 8: Answer the post-exercise questions

  1. According to "Introduction to Web services and the WSDK V5.1" from IBM at https://www6.software.ibm.com/developerworks/education/ws-intwsdk51/index.html, what are the four components in the definition of a Web Service?
  2. In what ways is Web Services an improvement over earlier technologies, including DCOM, Java RMI, and CORBA?
  3. Describe the two participants of the Web Service.
  4. What is WS-I and what is its purpose?
  5. In this exercise you used a script, WSDL2Java, to generate the Java files that you needed for your Web Service. Alternatively, we could have written the WSDL files and used these to generate the Java files. An instance of the WSDL protocol describes several things. Using the IBM Tutorial on "Describing Web services: WSDL", at https://www6.software.ibm.com/developerworks/education/ws-dewsdl/ws-dewsdl-2-1.html for further description if needed, give a brief description of these four WSDL items: messages, portTypes, bindings, and services.
  6. Describe the three main roles in a SOAP message transmission.
  7. Describe the four parts of a SOAP message.
  8. Given the example of a SOAP RPC-Style Call at https://www6.software.ibm.com/developerworks/education/ws-intwsdk51/ws-intwsdk51-4-3.html
    1. What tag indicates the start of the envelope element?
    2. Is there a header element? If so, what tag indicates the start of this element?
    3. What tag indicates the start of the body element?
    4. How many procedure calls are in the body? How many parameters does the getDVDs procedure have?
  9. What does UDDI stand for and what is it used for?
  10. What three kinds of registry data are supported by UDDI?

Also answer the following questions, which will help me to improve this assignment. Turn these answers in on a separate piece of paper without your name on it.

  1. How many hours did you spend on this assignment?

    Rate each of the following on a scale of 1-10 where 1 is "none/not at all" and 10 is "completely/definitely"

  2. Rate your prior experience with Web Services.
  3. The assignment was reasonable, given your starting skills.
  4. The preliminary reading material was sufficient. If it was not, can you describe what was missing?
  5. The assignment was comprehensible.
  6. The assignment was hard.
  7. It was helpful to have completed the RMI assignment prior to the Web Services assignment.
  8. The Web Services assignment depended on knowledge gained from the RMI assignment. If so, can you give some detail about what know from the RMI assignment helped in this assignment?
  9. I feel prepared to write a more advanced Web Service on my own.
  10. I understand what XML is and how it is used.
  11. I understand what SOAP is and how it is used.
  12. I understand what WSDL is and how it is used.
  13. I understand what UDDI is and how is is used.
  14. I wish that the assignment had covered more details on XML.
  15. I wish that the assignment had covered more details on SOAP.
  16. I wish that the assignment had covered more details on WSDL.
  17. I wish that the assignment had covered more details on UDDI.
  18. I wish that the assignment had covered more details on Apache and Axis.
  19. The tools on talon were sufficient for this assignment. If not, what tools would you suggest that we use instead?
  20. What would you change about this assignment?

References

Apache Web Services Project: http://ws.apache.org/
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/

Acknowledgements

This exercise was derived from the exercise used in CS493F04, Grid Computing, Western Carolina University, http://sol.cs.wcu.edu/~abw/CS493F04/ and 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.
Last modified: Sun Sep 19 17:47:13 Central Daylight Time 2004