• Table of contents
• Programming Guide - Web Services (RESTful)
  • Step-By-Step
  • Project Dependencies
• Coding Guidelines
  • Controller Layer
  • Services Layer

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:
   • Web Services/Controller - see Coding Guidelines
   • Services - see Coding Guidelines
   • DAO - optional but it's highly recommended to implement it
5. done

[resources]:

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:

• Nexus
• download web_inf_lib.zip and extract it to WEB-INF/lib folder

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);
    }
  }
  
  

  • for this example, the following web request will be mapped to the registerMember method:
    • request URL - http://.../.../reg-services/shopper
    • request method - POST

• 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 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.