Wednesday, September 28, 2011

Restful WebServices using Spring

In recent years, Representational State Transfer (REST) has emerged as a popular information-centric alternative to traditional SOAP-based web services. In Spring, REST support builds upon Spring MVC

The fundamentals of REST

Representational: REST resources can be represented in virtually any form, including XML, JavaScript Object Notation (JSON), or even HTML—whatever form best suits the consumer of those resources
State: when working with REST, we’re more concerned with the state of a resource than with the actions we can take against resources.
Transfer: REST involves transferring resource data, in some representational form, from one application to another.

REST is about transferring the state of resources—in whatever form is most appropriate from a server to a client (or vice versa).

Spring supports development of REST resources in the following ways:

  • Controllers can handle requests for all HTTP methods, including the four primary REST methods: GET, PUT, DELETE, and POST.
  • The new @PathVariable annotation enables controllers to handle requests for parameterized URLs (URLs that have variable input as part of their path).
  • The <form:form> JSP tag from Spring’s form-binding JSP tag library, along with the new HiddenHttpMethodFilter, make it possible to submit PUT and DELETE requests from HTML forms, even in browsers that don’t support those HTTP methods.
  • Resources can be represented in a variety of ways using Spring’s view and view resolvers, including new view implementations for rendering model data as XML, JSON, Atom, and RSS.
  • The representation best suited for the client can be chosen using the new ContentNegotiatingViewResolver
  • View-based rendering can be bypassed altogether using the new @ResponseBody annotation and various HttpMethodConverter implementations.
  • Similarly, the new @RequestBody annotation, along with HttpMethodConverter implementations, can convert inbound HTTP data into Java objects passed into a controller’s handler methods.

Spring MVC’s model for writing controller classes is extremely flexible. Almost any method with almost any signature can be annotated to handle a web request. But a side effect of such flexibility is that Spring MVC allows you to develop controllers that aren’t ideal in terms of RESTful resources. It’s too easy to write RESTless controllers.

Example of Spring MVC (Restless controller)

@Controller
@RequestMapping("/displaySpittle.htm")
public class DisplaySpittleController {

private final SpitterService spitterService;

@Inject
public DisplaySpittleController(SpitterService spitterService)
{
this.spitterService = spitterService;
}

@RequestMapping(method=RequestMethod.GET)
public String showSpittle(@RequestParam("id") long id, Model model)
{
 model.addAttribute(spitterService.getSpittleById(id));
 return "spittles/view";
}
 }

Take note of the @RequestMapping annotation at the class level. It says that this controller will handle requests for /displaySpittle.htm. That seems to imply that this controller is focused on the specific use case of displaying spittles (which is corroborated by the name of the class).

Nothing is terribly wrong with how DisplaySpittleController is written. But it isn’t a RESTful controller. It’s action-oriented and focused on a specific use case: displaying a Spittle object’s details in HTML form. Even the controller’s class name agrees.

Handling RESTful URLs URLs are one of the first things that most people think about when starting to work with REST.


is an example of Restless URL. This URL doesn’t locate or identify a resource. It demands that the server display a Spittle. The only part of the URL that identifies anything is the id query parameter. The base portion of the URL is verb-oriented. That is to say that it’s a RESTless URL


is an example of Restful URL. One thing that’s not clear about this URL is what it does. That’s because the URL doesn’t do any-thing. Rather, it identifies a resource. Instead of using a query parameter to identify the resource, the entire base URL identifies the resource. In fact, the new URL has no query parameters at all

To enable parameterized URL paths, Spring 3 introduced a new @PathVariable anno-tation. To see how this works, look at SpittleController, a new Spring MVC control- ler that takes a resource-oriented approach to handling requests for Spittles.

@Controller
@RequestMapping("/spittles")
public class SpittleController
{
private SpitterService spitterService;

@Inject
public SpittleController(SpitterService spitterService)
{
 this.spitterService = spitterService;
}

 @RequestMapping(value="/{id}", method=RequestMethod.GET)
 public String getSpittle(@PathVariable("id") long id, Model model)
{
 model.addAttribute(spitterService.getSpittleById(id));
return "spittles/view";
}
 }

You’re probably wondering about those weird curly-braces in the URL pattern. The part that says {id} is a placeholder through which variable data will be pass into the method. It corresponds to the @PathVariable annotation on the id method parameter.



Restful Code Example

Following is Code for a Customer Controller. In this Code I tried to implement all CUID methods for Customer Object

package com.playground.controller;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.ResponseStatus;

import com.playground.entity.Customer;
import com.playground.services.CustomerService;
@Controller

public class CustomerController {
            @Autowired @Qualifier("CustomerService")
            CustomerService service;
           
            @RequestMapping(value= "/findcustomer/{customerId}/",method={RequestMethod.GET})
            @ResponseStatus(HttpStatus.OK)
            public @ResponseBody String findCustomer(@PathVariable String customerId){
                        Customer c=service.findCustomer(customerId);
                        return "Here is Customer:"+c.getName();
            }
           
            @RequestMapping(value= "/savecustomers",method={RequestMethod.POST})
            @ResponseStatus(HttpStatus.CREATED)
            public @ResponseBody  String saveCustomer(@RequestParam(value="name") String name, @RequestParam(value="address", required=false) String address, @RequestParam(value="telephone") String telephone){
                         Customer c=new Customer();
                         c.setName(name);
                         c.setAddress(address);
                         c.setTelephone(telephone);
                         boolean result=service.saveCustomer(c);
                         if(result)
                                                return "Save Operation Completed Sucessfully";
                                    else
                                                return "Save Operation is not Sucessfull";
            }
           
            @RequestMapping(value= "/updatecustomers/{customerId}/{name}/{address}/{telephone}",method={RequestMethod.PUT})
            @ResponseStatus(HttpStatus.ACCEPTED)
            public  @ResponseBody String updateCustomerDetails(@PathVariable String customerId,@PathVariable String name, @PathVariable String address, @PathVariable String telephone){
                       
                        System.out.println("Here is the Customer Details:"+customerId+":"+name+":"+address+":"+telephone);
                         Customer c=new Customer();
                         c.setCustomerId(customerId);
                         c.setName(name);
                         c.setAddress(address);
                         c.setTelephone(telephone);
                         boolean result=service.updateCustomerDetails(c);
                         if(result)
                                                return "Update Operation Completed Sucessfully";
                                    else
                                                return "Update Operation is not Sucessfull";
            }
           
            @RequestMapping(value= "/deletecustomers/{customerId}",method={RequestMethod.DELETE})
            @ResponseStatus(HttpStatus.ACCEPTED)
            public  @ResponseBody String deleteCustomer(@PathVariable String customerId){
                                    System.out.println("Here is the Customer Id:"+customerId);
                                    boolean result=service.deleteCustomer(customerId);
                                    if(result)
                                                return "Delete Operation Completed Sucessfully";
                                    else
                                                return "Delete Operation is not Sucessfull";
            }
           
            @RequestMapping(value= "/allcustomers/",method={RequestMethod.GET})
            @ResponseStatus(HttpStatus.OK)
            public  @ResponseBody String getAllCustomers(){
                        List result=service.getAllCustomers();
                        return "Here is the list";
            }
           
}


URL for Find Customer

URL to Get All Customers

For Save Customer I have created a HTML form
Normal browsers doesn’t support PUT and DELETE HTTP method so I have created AJAX form to perform update and delete Operations

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Test Restful PlayGround</title>
   <script type="text/javascript" src="http://code.jquery.com/jquery-latest.js"></script>
    <script type="text/javascript">
            $(document).ready(function() {
                  //if submit button is clicked
                  $('#submit').click(function () {         
                        var customerId= $('input[name=customerId]');
                        //start the ajax
                        $.ajax({
                              //this is the php file that processes the data and send mail
                              url: "/RestfulPlayGround/deletecustomers/"+customerId.val(),     
                              type: "DELETE",
                              success: function (html) {                     
                                    alert(html);                 
                              }          
                        });
                        return false;
                  });  
                  $('#update').click(function () {         
                        //Get the data from all the fields
                        var customerId= $('input[name=customerId]');
                        var name= $('input[name=name]');
                        var address= $('input[name=address]');
                        var telephone= $('input[name=telephone]');
                       
                        //start the ajax
                        $.ajax({
                              //this is the php file that processes the data and send mail
                              url: "/RestfulPlayGround/updatecustomers/"+customerId.val()+"/"+name.val()+"/"+address.val()+"/"+telephone.val(),  
                              type: "PUT",
                              success: function (html) {                     
                                    alert(html);                 
                              }          
                        });
                        return false;
                  });  

            });  
    </script>
</head>
<body>
<br>
Delete Customer

<form  method="post">
<br>
Customer Id:<input type="text" name="customerId"><br>
<input type="submit" value="Submit" id="submit"/>
</form>


<br>
Update Customer
<form method="post">
<br>
Customer Id:<input type="text" name="customerId"><br>
Name:<input type="text" name="name"><br>
Address:<input type="text" name="address"><br>
Telephone:<input type="text" name="telephone"><br>
<input type="submit" id="update" value="Update">
</form>
<br>
Save Customer
<form method="POST" action="/RestfulPlayGround/savecustomers">
<br>
Name:<input type="text" name="name"><br>
Address:<input type="text" name="address"><br>
Telephone:<input type="text" name="telephone"><br>
<input type="submit" value="Save" id="save">
</form>

</body>
</html>

Complete Application Source Code is Present at following location
https://docs.google.com/viewer?a=v&pid=explorer&chrome=true&srcid=0B0YFdqXJcI3mYzM5ZDg0OTQtOTI1MS00YjBiLThhNjQtMTU1MTFmOWRlYjc2&hl=en

Reference: Spring in Action 3

3 comments:

  1. Your post really helped me to understand the Restful Web Services using Spring . It has great details and yet it is easy to understand.
    That's what i was looking for. I will definitely share it with others.

    Thanks for sharing.

    ReplyDelete
  2. very helpful for beginners spring3+rest, thanks for providing code.

    ReplyDelete