Assignment 1

Assignment 1 A Generic Web Service Compiling, Deploying, and Modifying a Simple Web Service 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:

1 of 12

Assignment 1

ssh foo@bar.com where 'foo' is the user name and 'bar.com' is the host. 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 !ws (Java web service) file. Generate several Java source files representing the service from that !ws 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. 2 of 12

Assignment 1

Step 1 - Preparation of Directory Structure Once you have logged into the server you will be using for this assignment, create a directory in your home directory called "eb#er$ices using the command mkdir "eb#er$ices: [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 "eb#er$ices': [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 %y%ath which resides in the file %y%ath.!ws. Using your favorite text editor, type in this class and save it into the correct file: public class %y%ath & public int s'uared( int ) * & return ) + ), 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 ./0102340 56%7/webapps/a)is/yourusername/. ./0102340 56%7 is the environment variable specifying the path to the home directory of the Apache Tomcat java servlet container. Copy your %y%ath.!ws file to the ./0102340 56%7/webapps/a)is/yourusername/ directory by using the following command: [yourusername@someserver WebServices]$ cp MyMath.jws \

3 of 12

Assignment 1

$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 browser to the following url, you will be able to see how your service is deployed. (http://yourser$er.yourdomain.edu:8989/a)is/yourusername/) This should bring up a window that looks similar to the following:

Notice that you now have a %y%ath.!ws 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.w:.org/1;/wsdl, which specifies that operations are exposed through the web service clients. Axis ( http://ws.apache.org/a)is/) is an implementation of the Simple Object Access Protocol (SOAP). Use Axis tool "#<2=>a$a to generate the Java source files needed by a client to access the web service from the %y%ath.!ws 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

4 of 12

Assignment 1

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 >a$a="#<2. The >a$a="#<2 tool creates a WSDL document [that] will contain the appropriate WSDL types, messages, portType, bindings and service descriptions to support a SO ! rpc, encoding web service" #$ In order to use this tool, you must define a class, %y%ath.!a$a, that contains the same contents as the %y%ath.!ws 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.a)is.wsdl.>a$a="#<2 argument gives the package information on where to find the >a$a="#<2 class. The ?o %y%ath.wsdl argument gives the filename of the output WSDL file. The ?l@http://localhost:8989/a)is/yourusername/%y%ath@' argument gives the location of the service in question.

The output of this command is a single WSDL file called %y%ath.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
#

http%&&ws"apache"org&a'is&(ava&user)guide"html*+ava,WSDL-uildingWSDL.rom+ava

5 of 12

Assignment 1

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

6 of 12

Assignment 1

<wsdlsoap:address location="http://localhost:8080/axis/testaccount/MyMa th"/> </wsdl:port> </wsdl:service> </wsdl:definitions>

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.a)is.wsdl."#<2=>a$a argument defines which package the "#<2=>a$a class resides in. The ?o argument specifies that the output files should be placed in the current directory. The ?s # true argument specifies that the server side bindings and the skeleton should be deployed. The ?d #ession argument specifies that the build should be done on a Session basis. The ?p localhost.a)is.yourusername.%y%ath !ws 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/"eb#er$ices/', 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

7 of 12

Assignment 1

The "#<2=>a$a program will locate the %y%ath.!ws 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 "#<2=>a$a program is a directory inside of '/home/yourusername/"eb#er$ices/' called 'localhost'. You can use the ls command to view this. The 'localhost' directory has a subdirectory named 'a)is' which has another subdirectory named 'yourusername' which has a subdirectory named '%y%ath !ws'. This series of directories was created because it follows the parts of the URL provided above. The directory ' %y%ath !ws' has four files within it: %y%ath.!a$a: source for the Java interface for MyMath class. %y%ath#er$ice.!a$a: source for the Java interface that includes the get%y%ath method specification. %y%ath#er$ice2ocator.!a$a: source for the Java class %y%ath#er$ice2ocator. %y%ath#oapAinding#tub.!a$a: source for the Java class %y%ath#oapAinding#tub. These files are the Java source files created by "#<2=>a$a and are needed to make %y%aths client. The command invoking "#<2=>a$a 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, yourser$er.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/"eb#er$ices' compile the four Java source files generated by the previous step with the command: [yourusername@someserver WebServices]$ javac -classpath \ $AXISCLASSPATH:$CLASSPATH \

8 of 12

Assignment 1

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 "#<2=>a$a command as described earlier. Step 5 - Write the Client Source While you are still in the directory '/home/yourusername/"eb#er$ices/' create a file named '%y%ath/lient.!a$a' that contains the code for the client. The client source code that you are to place in the ' %y%ath/lient.!a$a' file is given below. The import statements will assume that you invoked the "#<2=>a$a program using localhost, not yourser$er.yourdomain.edu.
// ;e'uired for 0)is B.B: import localhost.a)is.yourusername.%y%ath !ws.%y%ath#er$ice2ocator, import localhost.a)is.yourusername.%y%ath !ws.%y%ath#er$ice, import localhost.a)is.yourusername.%y%ath !ws.%y%ath, import org.apache.a)is.client.+, // 0)is B.B import import import import org.apache.a)is.encoding.C%21ype, org.apache.a)is.utils.6ptions, !a$a.net.+, !a$a).)ml.rpc.Earameter%ode, // // // // ;e'uired ;e'uired ;e'uired ;e'uired as of 0)is B.= as of 0)is B.= for D;2 as of 0)is B.=

public class %y%ath/lient & public static $oid main(#tring argsFG* throws 7)ception & %y%ath#er$ice ser$ice H new %y%ath#er$ice2ocator(*, // locate the ser$ice 3nteger ) H new 3nteger(argsFBG*, // 1ake the command line parameter // and generate an 3nteger ob!ect. 6ptions options H new 6ptions( args *, // Eassing arguments. ;e'uired // for getEort command. #tring endpoint H Ihttp://localhost:I J options.getEort(* J I/a)is/yourusername/%y%ath.!wsI, // 1ell the class where to // look for ser$ice. /all call H (/all* ser$ice.create/all(*, // <esignate that a call will // be made. call.set1arget7ndpoint0ddress( new D;2( endpoint * *, // designate the // target ser$ice call.set6peration4ame( Is'uaredI *, // the method name of the ser$ice // define the parameters that the method re'uires. call.addEarameter( IopBI K C%21ype.C#< 341K Earameter%ode.34*, // define the parameters that the method returns. call.addEarameter( Iop=I K C%21ype.C#< 341 K Earameter%ode.6D1 *,

9 of 12

Assignment 1 // #et the return type of the call. (;e'uired because of addEarameter.* call.set;eturn1ype( C%21ype.C#< 341 *, // 5old the result of the method call and make the call. (3n$oke must // always ha$e an array of ob!ects passed to it.* int ret H (3nteger* call.in$oke( new 6b!ectFG & ) - *, // #how the result: #ystem.out.println( I1he s'uare of L J ) J L is L J 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/"eb#er$ices/' compile the client code with: [yourusername@someserver WebServices]$ javac -classpath \ $AXISCLASSPATH:$CLASSPATH:. MyMathClient.java Be careful to ensure there is at least one space before the argument '%y%ath/lient.!a$a' to separate it from the previous argument. The previous argument, '.0C3#/20##E015:$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/"eb#er$ices/' execute the client code with: [yourusername@someserver WebServices]$ java -classpath \ $AXISCLASSPATH:$CLASSPATH:. MyMathClient p8080 4 The argument -p8989 tells the client which port to work with. There should not be a space between ?p and 8989. 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

10 of 12

Assignment 1

also must extend the client to test the new methods. The method named isErime 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/Erime4umber.html.) The method named is7$en 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/7$en4umber.html)

To do this, the basic idea is to repeat the first six steps above but adding in the extra code in the '%y%ath.!ws' and '%y%ath/lient.!a$a' files. All the steps are to be done while you are in the directory '/home/yourusername/"eb#er$ices/'. Appendix A: Additional Resources Apache web services Project: http://ws.apache.org/ Apache Axis: http://ws.apache.org/a)is Apache ANT: http://ant.apache.org Apache Tomcat: http://!akarta.apache.org Web Service Description Language: http://www.w:.org/1;/wsdl On To Java Axis web services: http://www.on!a$a.com/lpt/a/BMN8 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.e)e'. 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 12

Assignment 1

12 of 12