Project

General

Profile

Actions

Programming Guide - Web Services (RESTful) » History » Revision 2

« Previous | Revision 2/4 (diff) | Next »
chin-yeh, 12/27/2011 12:00 PM


Programming Guide - Web Services (RESTful)

This guide describes how to develop the RESTful based web services.

In general, the web services should contains the following layers:
  • Web Services Layer (a.k.a controller) - this is the only place where the client will talk to
  • Services Layer - contains the business logic on how to handle the client's request
  • DAO layer - contains the logic on how to retrieve & persist data

Step-By-Step

Assume that you have setup the Eclipse environment

  1. launch Eclipse
  2. create a new Dynamic Web Project:
    • Dynamic web module version should set to 2.4 or above
    • JDK compiler compliance version should set to 5.0 or above
  3. and then configure the project:
    1. obtain the project dependencies and then place it in the WEB-INF/lib folder
    2. replace the web.xml with this web.xml
    3. create the following folder:
      • src/META-INF/spring
    4. copy applicationContext.xml to src/META-INF/spring folder
      • edit the following line to put in the root package of the project
        <context:component-scan base-package="my.root.package"/>
        
    5. copy restful-servlet.xml to src/META-INF/spring folder
      • edit the following line to put in the package name which contains all of the controller classes
        <context:component-scan base-package="my.package.controller"/>
        
  4. after configured the project, let's start coding the following layers:
  5. done

download this sample project, sample_restful_project.zip to view all code snippets

Project Dependencies

  • com.springsource.org.aopalliance-1.0.0.jar
  • jackson-core-asl-1.9.0.jar
  • jackson-jaxrs-1.9.0.jar
  • jackson-mapper-asl-1.9.0.jar
  • jcl-over-slf4j-1.6.1.jar
  • org.springframework.aop-3.0.5.RELEASE.jar
  • org.springframework.asm-3.0.5.RELEASE.jar
  • org.springframework.beans-3.0.5.RELEASE.jar
  • org.springframework.context.support-3.0.5.RELEASE.jar
  • org.springframework.context-3.0.5.RELEASE.jar
  • org.springframework.core-3.0.5.RELEASE.jar
  • org.springframework.expression-3.0.5.RELEASE.jar
  • org.springframework.jdbc-3.0.5.RELEASE.jar
  • org.springframework.transaction-3.0.5.RELEASE.jar
  • org.springframework.web.servlet-3.0.5.RELEASE.jar
  • org.springframework.web-3.0.5.RELEASE.jar
  • slf4j-api-1.6.1.jar
  • slf4j-log4j12-1.6.1.jar
  • spring-security-config-3.0.5.RELEASE.jar
  • spring-security-core-3.0.5.RELEASE.jar
  • spring-security-web-3.0.5.RELEASE.jar
These dependencies can be found in:

Coding Guidelines

This guidelines will be revised anytime to accommodate requirement changes.

Controller Layer

  • the controller class must be thread safe as there's only one instance will be created to serve all web request
  • every controller must annotated with @Controller at the class level
    @Controller
    public class RegistrationController {
      ...
    }
    
  • use the @RequestMapping to map the web request to the handler class or handler method, e.g.:
    @Controller
    @RequestMapping(value = "/reg-services")
    public class RegistrationController {
    
      @RequestMapping(value = "/shopper", method = RequestMethod.POST)
      @ResponseBody
      public boolean registerMember(@RequestBody MemberRegistrationRequest request) {
            return registrationServices.registerMember(request);
      }
    }
    
  • refer to this link for the guidelines about how to choose the appropriate HTTP methods and request URI
  • every method handler should be annotated with @ResposeBody at the method level and return a value (do not return void)
    @ResponseBody
    public boolean registerMember(@RequestBody MemberRegistrationRequest request) {
       return registrationServices.registerMember(request);
    }
    
  • if an argument is annotated with @RequestBody, the body of the web request will be automatically parsed.
    public boolean registerMember(@RequestBody MemberRegistrationRequest request) {
    
  • to bound the value of a URI template variable, just annotate, @PathVariable to the target argument
    @RequestMapping(value = "/shopper/{shopperRefNo}", method = RequestMethod.GET)    
    @ResponseBody
    public MemberInfo retrieveMemberInfo(@PathVariable int refNo) {
    ...
    
    • for this example, the value of the URI template variable, shopperRefNo will be bound to the argument, refNo.
  • use @RequestParam to access the specific Servlet request paramater. Parameter values will be converted to the declared argument type.
    public String setupForm(@RequestParam("petId") int petId)
    
    • note: By default, the parameter is required. To make the parameter as optional, set the required attribute to false, e.g.:
      • @RequestParam(value="id", required=false)

Services Layer

  • the service class is just a POJO (plain-old-java-object)
  • the service class must be thread safe if, and only if it is one of the field members of the controller
  • the service class should contains the business logics only. Try to delegate the un-relevant codes to other appropriate layers.

Updated by chin-yeh almost 13 years ago · 2 revisions