Tutorial 1 - Web Services

The purpose of this tutorial is to introduce RESTful and SOAP web services. For the RESTful web services we will use the Restlet platform (an implementation of the JSR311 specification - JAX-RS Java API for RESTful Web Services). For SOAP style web services we will use the Axis 2 Web Service engine. During the tutorial, a teacher will be present to help with any practical issues that may arise. If you finish the tutorial ahead of time, you are recommended to get started on assignment 1. This tutorial is volountary and your work will not be graded.

RESTful Web Services

  1. Download RESTlets from here.
  2. Unzip the downloaded file into some directory, let us call the created directory RESTLETS_HOME.
  3. Download the sample service from here.
  4. Set the environment variable RESTLETS_LIB to $RESTLETS_HOME/lib
  5. Compile the sample service: 'ant'
  6. Start the sample service (embedded HTTP server): './server.sh'
  7. Try the sample clients {post,put,get,delete}.sh. A typical session is outlined below. Here, we create three items, list all available items, update the description of an item and inspect the result. Next, we delete an item, and finally, inspect the updated list of items.
    • ./post.sh item1 "A description of item1"
    • ./post.sh item2 "A somewhat more detailed description of item 2"
    • ./post.sh item3 "Yet another item"
    • ./get.sh
    • ./put.sh item2 "An updated description of item2"
    • ./get.sh item2
    • ./delete.sh item1
    • ./get.sh
  8. In the server terminal, you will see the HTTP command that correspond to these requests, and the respective responses.
  9. Also note that this service can be accessed through a standard web browser, take a look at e.g., http://localhost:8182/items
  10. Familiarize yourself with the sample service. Note how we define the resource types (ItemResource.java, ItemsResource.java) of the service. Observe how the FirstResourceApplication specifies a router to forward incoming requests to the correct resource implementation. Also note how FirstResourceMain.java launches the embedded HTTP server.
  11. Implement a simple service that manages mailing lists. Each mailing list has a name, and contains one or more email addresses. The following four step process can be applied when creating a RESTful interface:
    1. Define the resource types, including the data they contain and what their URIs should look like.
    2. Decide how to represent the resources in the system, XML is one, but no means the only choice.
    3. Decide what methods (POST, PUT, GET, and DELETE) are applicable to what resource type, and what the service-side implementation of these should look like.
    4. Define what HTTP status codes are applicable for the operations. Although the RESTlet framework hides the detail of these, a complete list of HTTP return codes is a useful part of the documentation of your service, and allows client developers to know what return codes to test for.
  12. Embed your new mailing list service into a servlet, and deploy that servlet in tomcat. In this scenario, tomcat replaces the embedded HTTP server. Here are some guidelines for tomcat deployment.

SOAP Web Services

For the purpose of this tutorial (and assignment 1), students are provided with a preconfigured Axis2 development environment.

In this tutorial, you will use an example Web Service and incrementally extend the capabilities of the service client and service implementations.

  1. download the development environment package from the downloads directory and install it using the instructions found on the Axis2 development environment page.
  2. set environment variables and start the Axis2 container
    • set environment variables: source env.sh
    • start container: axis2-1.5/bin/axis2server.sh
  3. download, build, deploy, and test the AXIOM hello world example Web Service (separate shell)
    • set environment variables: source env.sh
    • install service: unzip axis2_sample_axiom.zip
    • enter service working directory: cd hws_axiom
    • build service: ant dist
    • deploy service: ant deploy
    • test service: ./scripts/greet.sh <yourname> <yourmessage>
    • undeploy service: ant undeploy
  4. inspect the service WSDL and investigate how it maps to the service code
  5. find a WSDL validator and validate the service WSDL (optional)
  6. download the Apache TCP Monitor and use it to inspect the SOAP traffic between client and service
  7. extend the hello world web service to include a method named "sayHello" that uses the same parameter format as greet()
  8. create a service client that uses the sayHello() method
  9. change the parameter format of sayHello() to use a new datatype of your own design
  10. extend the service to have two new methods, one that uses a single parameter and one that uses arrays of your data type
  11. download the WSDL2Java hello world example Web Service, repeat (some of) the steps above, and investigate how to generate service client stubs
  12. investigate how to invoke web services using HTTPS