Restful code example using Spring MVC

In my previous blog, I talked about Restful webservices design. In this blog, I will provide sample code for the same using Spring MVC framework.

Spring MVC 3.x supports annotation based controllers, which are Restful in nature. 

Let us create a sample Spring web application for performing CRUD on User entity.


Creating project:

Create a Maven project with a archetype 'maven-archetype-webapp'.

pom.xml

<!-- version property -->
<properties>
    <spring.version>3.1.2.RELEASE</spring.version>
</properties>
<!-- servlet dependency for compilation -->
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>servlet-api</artifactId>
    <version>2.5</version>
    <type>jar</type> 
    <scope>compile</scope>
</dependency>

<!-- Spring MVC dependencies -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>${spring.version}</version>
</dependency>

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>${spring.version}</version>
</dependency>

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>${spring.version}</version>
</dependency>

<!-- Jackson dependency for JSON mapping-->
<dependency>
    <groupId>org.codehaus.jackson</groupId>
    <artifactId>jackson-mapper-asl</artifactId>
    <version>1.9.13</version>
</dependency>


web.xml

<servlet>
    <servlet-name>mvc-dispatcher</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>mvc-dispatcher</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

<context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/mvc-dispatcher-servlet.xml</param-value>
</context-param>
 
<listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener
    </listener-class>
</listener>

The servlet-name is 'mvc-dispatcher'. So we need a context xml with the name mvc-dispatcher-servlet.xml

mvc-dispatcher-servlet.xml


<beans xmlns="http://www.springframework.org/schema/beans"  
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:mvc="http://www.springframework.org/schema/mvc"  
          xmlns:context="http://www.springframework.org/schema/context" 
          xmlns:util="http://www.springframework.org/schema/util"  
          xsi:schemaLocation="http://www.springframework.org/schema/mvc 
                              http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd
                              http://www.springframework.org/schema/beans 
                              http://www.springframework.org/schema/beans/spring-beans-3.0.xsd         
                              http://www.springframework.org/schema/context 
                              http://www.springframework.org/schema/context/spring-context-3.0.xsd 
                              http://www.springframework.org/schema/util 
                              http://www.springframework.org/schema/util/spring-util.xsd">   

          <context:component-scan base-package="com.myorg" />
 
          <mvc:annotation-driven/>
  
          <bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
                <property name="messageConverters">
                <util:list id="beanList">
                    <ref bean="stringHttpMessageConverter"/>        
                </util:list>
                </property>
          </bean>
   
          <bean id="stringHttpMessageConverter" 
                              class="org.springframework.http.converter.StringHttpMessageConverter"/>
 
          
          <bean class="org.springframework.web.servlet.view.ContentNegotiatingViewResolver">
                 <property name="mediaTypes">
                 <map>
                    <entry key="html" value="text/html"/>
                    <entry key="json" value="application/json"/>
                 </map>
                 </property>
                 <property name="viewResolvers">
                      <list>
                      <bean class="org.springframework.web.servlet.view.BeanNameViewResolver"/>
                      <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
                          <property name="prefix" value="/WEB-INF/jsp/"/>
                          <property name="suffix" value=".jsp"/>
                      </bean>
                      </list>
                 </property>
                 <property name="defaultViews">
                    <list>
                        <bean class="org.springframework.web.servlet.view.json.MappingJacksonJsonView" />
                    </list>
                 </property>
         </bean>
</beans>

Things to know:

  • The namespaces in the beans element are very important as the spring container validates this xml against the xsd.
  • Every xmlns attribute should have a corresponding entry in the xsi:schemaLocation attribute. Here we have used mvc, context, util prefixes.
  • 'component-scan' element tells the spring container to look for com.myorg package for annotated controllers.
  • 'mvc:annotation-driven' tells the spring container that we are using annotated controllers.
  • InternalResourceViewResolver is used to indicate that the views are present in '/WEB-INF/view/' folder with jsp extension.
  • The ContentNegotiatingViewResolver is used to produce the correct format of response from our controllers. For Restful webservices, we will need response formats like JSON,html,xml etc. 
  • MappingJacksonJsonView is used to convert Java POJO to JSON format.


User POJO:

public class User implements Serializable{
    private static final long serialVersionUID = 10008L;
 
    private String firstName;
    private String lastName;
    private long userId;
 
    public User(String _first, String _last){
      this.firstName = _first;
      this.lastName  = _last;
    }
 
    public User(){  
    }
    
    //Setters and Getters
}  

User Service:

The service is a trivial implementation for brevity.


public interface UserService {
    public User createUser(User user) throws UserCreateException;
    public User getUser(String userId) throws UserNotFoundException;
    public void updateUser(User user) throws UserNotFoundException;
    public void deleteUser(String userId) throws UserNotFoundException;
}

Implementation is provided below. Note the @service annotation which is then injected into the controller using autowiring.


@Service
public class UserServiceImpl implements UserService{
    public User createUser(User user) throws UserCreateException{
       //implement here
       user.setUserId(111);
       return user;
    }

    public User getUser(String userId) throws UserNotFoundException{
       User user = new User();
       if(userId == null){
           throw new UserNotFoundException("Invalid User Id");
       }
       user.setFirstName("John");
       user.setLastName("Howard");
       return user;
    }

    public void updateUser(User user) throws UserNotFoundException{
       //implement here
    }

    public void deleteUser(String userId) throws UserNotFoundException{
      //implement here
    }
}

Exception classes


public class ServiceException extends Exception{
     private static final long serialVersionUID = 1L;
 
     public ServiceException(String _msg){
         super(_msg);
     }
}

public class AuthenticationException extends ServiceException{
    private static final long serialVersionUID = 1L;
  
    public AuthenticationException(String _msg){
        super(_msg);
    } 
}

public class UserCreateException extends ServiceException{
    private static final long serialVersionUID = 1L;
 
    public UserCreateException(String _msg){
        super(_msg);
    }
}
  
public class UserNotFoundException extends ServiceException{
    private static final long serialVersionUID = 1L;
 
    public UserNotFoundException(String _msg){
       super(_msg);
    }
}


UserController:


@Controller
public class UserController extends AbstractController{
 
    @Autowired
    private UserService userService;
 
    @RequestMapping(value="/restexample/users/user",method=RequestMethod.POST,
                    produces="application/json")
    @ResponseBody
    public User createUser(@RequestBody String body, HttpServletRequest _request) 
                           throws UserCreateException,AuthenticationException{
  
         authenticate(_request, "createUser");
  
         String firstName = _request.getParameter("firstName");
         String lastName = _request.getParameter("lastName");

         User user = new User(firstName,lastName);

         user = userService.createUser(user);

         return user;
    }
 
    /*Invoked depending on accept header*/
 
    @RequestMapping(value="/restexample/users/user/{userId}",method=RequestMethod.GET,
                    produces="application/json")   
    @ResponseBody
    public User getUser(@PathVariable String userId,HttpServletRequest _request) 
                        throws UserNotFoundException,AuthenticationException{
   
        authenticate(_request, "getUser");
        return userService.getUser(userId);
    }
 
    @RequestMapping(value="/restexample/users/user/{userId}",method=RequestMethod.GET)   
    @ResponseBody
    public String getUserAsHTML(@PathVariable String userId,HttpServletRequest _request) 
                               throws UserNotFoundException,AuthenticationException{

        authenticate(_request, "getUser");
        User user =  userService.getUser(userId);

        StringBuilder builder = new StringBuilder();
        builder.append("FirstName: ").append(user.getFirstName());
        builder.append("LastName: ").append(user.getLastName());
    
        return builder.toString();
    }
 
    @RequestMapping(value="/restexample/users/user/{userId}",method=RequestMethod.PUT)
    @ResponseBody
    public String updateUser(@PathVariable String userId,@RequestBody String body, 
                                  HttpServletRequest _request) 
                           throws UserNotFoundException,AuthenticationException{
   
        authenticate(_request, "updateUser");
        long userIdVal = convertStringToLong(userId);

        if(userIdVal < 1){
             throw new UserNotFoundException("Not a valid User Id: "+userId);
        }

        String firstName = _request.getParameter("firstName");
        String lastName = _request.getParameter("lastName");

        User user = new User(firstName,lastName);
        user.setUserId(userIdVal);

        userService.updateUser(user);
        return "success";
    }
 
    @RequestMapping(value="/restexample/users/user/{userId}",method=RequestMethod.DELETE)
    @ResponseBody
    public String deleteUser(@PathVariable String userId,@RequestBody String body, 
                                  HttpServletRequest _request) 
                           throws UserNotFoundException,AuthenticationException{

        authenticate(_request, "createUser");

        User user = new User();

        userService.deleteUser(userId);
        return "success";
    }
 
    public void authenticate(HttpServletRequest _request, String _serviceName) 
                             throws AuthenticationException{

        String hashKey = _request.getHeader("hashKey");
        boolean valid = true;
        //validate hashkey
        if(!valid){
             throw new AuthenticationException(_serviceName);
        }
    }
}


AbstractController:



public abstract class AbstractController {
 
  private final String USER_NOT_FOUND_ERROR_CODE = "1002";

  private final String USER_NOT_FOUND_ERROR_DESC = "The provided user cannot be found.";

  private final String AUTHENTICATION_ERROR_CODE = "1003";

  private final String AUTHENTICATION_ERROR_DESC = "You are not authorized to access this service.";

  private final String USER_CREATION_ERROR_CODE = "1001";

  private final String USER_CREATION_ERROR_DESC = "User creation failed. ";

  private final String UKNOWN_ERROR_CODE = "1000";

  private final String UKNOWN_ERROR_DESC = "An unknown error has occurred";

 
  @ExceptionHandler(ServiceException.class)
  @ResponseBody
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  public RestError handleServiceException(ServiceException ex, HttpServletResponse _request){
      RestError error = new RestError();

      if(ex instanceof AuthenticationException){
        error.setErrorCode(AUTHENTICATION_ERROR_CODE);
        error.setErrrorDesc(AUTHENTICATION_ERROR_DESC);
      }
      else if(ex instanceof UserCreateException){
        error.setErrorCode(USER_CREATION_ERROR_CODE);
        error.setErrrorDesc(USER_CREATION_ERROR_DESC);
      }
      else if(ex instanceof UserNotFoundException){
        error.setErrorCode(USER_NOT_FOUND_ERROR_CODE);
        error.setErrrorDesc(USER_NOT_FOUND_ERROR_DESC);
      }
      else {
        error.setErrorCode(UKNOWN_ERROR_CODE);
        error.setErrrorDesc(UKNOWN_ERROR_DESC);
      }
      return error;
  }
}

RestError:


public class RestError implements Serializable{
    private static final long serialVersionUID = 198L;
 
    private String errorCode;
    private String errrorDesc;
 
    //Setters and getters
}

Things to know:


  • The controller extends from AbstractController which is explained later.
  • @RequestMapping can be used to map the Rest URI to the method. We can add parameters to the URI like {userId}
  • The parameters are mapped to variables through PathVariable
  • The method can declare what media type it is consuming/producing. For eg, produces="application/json"
  • The method can also declare what request type it is accepting through method=RequestMethod.POST/PUT/GET etc.
  • The accept header set by the client will be used to determine the method to be invoked.
  • The method can declare that it is returning a response in the Response body through @ResponseBody.
  • If the response type is a custom object like 'User', Jakson Mapping view will convert it to JSON format if required.
  • The authentication performed here is simple authentication by using a secret hash key (which is preagreed by client/server).This hash key is sent across in the request header. 
  • The same URI can be mapped to send across different response formats.
  • The getUserAsHTML() and getUser() map to same URI. However, getUserAsHTML() returns html content (the method can return a div content) whereas getUser() returns JSON content.


Handling exceptions:

The @ExceptionHandler annotation could be used to handle the exceptions. However, Spring requires every controller to have its own @ExceptionHandler annotated method.

To overcome this, we can have an abstract controller and have the exception handling at a common place. We can have different methods for each type of exception, or as in the example, we can handle the super exception class which is ServiceException and then handle individually.
If you are using Spring 3.2, you can use the @controlleradvice annotation and use any class for exception handling.

Rest Services generally should provide meaningful error messages and custom error codes when there is an error. At the same time, it should also prevent the internal exception hierarchy from reaching the client. In our example, the RestError object will which is returned by the exception handler will be converted to JSON format and returned back to the client.

Note that the error messages could be enumerated for better clarity.



Testing:

I have used Soap Client for testing. We can set the request type POST/GET etc and aslo the accept headers (application/json etc)

Following is the sample responses for a few requests:


Error Response:



HTTP response:
HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 20 Aug 2013 11:26:01 GMT
Connection: close

{"errorCode":"1003","errrorDesc":"You are not authorized to access this service. "}

JSON:
{
   "errorCode": "1003",
   "errrorDesc": "You are not authorized to access this service. "
}

Success response as JSON:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Tue, 20 Aug 2013 11:58:09 GMT

{"firstName":"John","lastName":"Howard","userId":111}

Comments

  1. thanks for ur post
    please tell me url for test via SOAP UI

    thanks again :-)

    ReplyDelete
  2. Hi Thanks for visit us:

    ARKA Softwares & Outsourcing is an IT Company focusing on software & Web development and providing offshore outsourcing solutions to enterprises worldwide.website designing company in usa

    ReplyDelete
  3. I really enjoy simply reading all of your weblogs. Simply wanted to inform you that you have people like me who appreciate your work. Definitely a great post I would like to read this
    angularjs online Training

    angularjs Training in marathahalli

    angularjs interview questions and answers

    angularjs Training in bangalore

    angularjs Training in bangalore

    angularjs online Training

    ReplyDelete
  4. This is most informative and also this post most user friendly and super navigation to all posts... Thank you so much for giving this information to me.

    rpa training in chennai
    rpa training in bangalore
    rpa course in bangalore
    best rpa training in bangalore
    rpa online training

    ReplyDelete
  5. I think you have a long story to share and i am glad after long time finally you cam and shared your experience.
    python course institute in bangalore
    python Course in bangalore
    python training institute in bangalore

    ReplyDelete
  6. Really very nice blog information for this one and more technical skills are improve,i like that kind of post.
    Devops Training courses
    Devops Training in Bangalore
    Best Devops Training in pune
    Devops interview questions and answers

    ReplyDelete
  7. Greetings. I know this is somewhat off-topic, but I was wondering if you knew where I could get a captcha plugin for my comment form? I’m using the same blog platform like yours, and I’m having difficulty finding one? Thanks a lot.

    Advanced AWS Online Training | Advanced Online AWS Certification Course - Gangboard
    Best AWS Training in Chennai | Amazon Web Services Training Institute in Chennai Velachery, Tambaram, OMR
    Advanced AWS Training in Bangalore |Best AWS Training Institute in Bangalore BTMLA ,Marathahalli

    ReplyDelete
    Replies
    1. Hi Thomas,
      I am not aware of a captcha plugin. I have not seen anybody using that in this platform.

      Delete
  8. This comment has been removed by the author.

    ReplyDelete
  9. I really liked one site sitting at home I managed to make some money superior play online casino go and see how i did it

    ReplyDelete
  10. This is best one article so far I have read online, I would like to appreciate you for making it very simple and easy
    Regards,

    DevOps Training
    DevOps Training institute in Ameerpet
    DevOps Training institute in Hyderabad
    DevOps Training Online
    DevOps Training Institute

    ReplyDelete
  11. For Devops Training in Bangalore visit : Devops training in Bangalore

    ReplyDelete
  12. Such great information for blogger iam a professional blogger thanks…

    Looking for Hadoop Admin Training in Bangalore, learn from Softgen Infotech provide Hadoop Admin Training on online training and classroom training. Join today!

    ReplyDelete
  13. It is amazing and wonderful to visit your site.Thanks for sharing this information,this is useful .Manual Testing Training in Bangalore

    ReplyDelete
  14. I have read your blog its very attractive and impressive. I like it your blog. SELENIUM training in bangalor

    ReplyDelete
  15. Great post!I am actually getting ready to across this information,i am very happy to this commands.Also great blog here with all of the valuable information you have.Well done,its a great knowledge.DOTNET training in bangalore

    ReplyDelete
  16. Thanks for one marvelous posting! I enjoyed reading it; you are a great author. I will make sure to bookmark your blog and may come back someday. I want to encourage that you continue your great post.Microsoft Dynamics CRM Training in Bangalore

    ReplyDelete

  17. Thank you for your post. This is excellent information. It is amazing and wonderful to visit your site.windows azure cloud computing training in bangalore


    ReplyDelete
  18. I am happy for sharing on this blog its awesome blog I really impressed. thanks for sharing.

    Became an Expert In Cloud Computing Security Training! Learn from experienced Trainers and get the knowledge to crack a coding interview, @Softgen Infotech Located in BTM Layout.

    ReplyDelete
  19. really it is an awesome information keep on doing...


    https://www.acte.in/angular-js-training-in-chennai
    https://www.acte.in/angular-js-training-in-annanagar
    https://www.acte.in/angular-js-training-in-omr
    https://www.acte.in/angular-js-training-in-porur
    https://www.acte.in/angular-js-training-in-tambaram
    https://www.acte.in/angular-js-training-in-velachery

    ReplyDelete
  20. Gone through this wonderful coures called Salesforce Certification Training in Dallas who are offering fully practical course, who parent is Salesforce Training in USA and they have students at Salesforce Training classes in Canada institutes.

    ReplyDelete
  21. wonderful article. Very interesting to read this article.I would like to thank you for the efforts you had made for writing this awesome article.Thanks for sharing such a good blog. You’re doing a great job. Keep posting like this useful info !! DevOps Training in Chennai | DevOps Training in anna nagar | DevOps Training in omr | DevOps Training in porur | DevOps Training in tambaram | DevOps Training in velachery

    ReplyDelete
  22. This is most informative and also this post most user friendly and super navigation to all posts... Thank you so much for giving this information to me.keep update your post
    AngularJS training in chennai | AngularJS training in anna nagar | AngularJS training in omr | AngularJS training in porur | AngularJS training in tambaram | AngularJS training in velachery

    ReplyDelete
  23. This is most informative and also this post most user friendly and super navigation to all posts... Thank you so much for giving this information to me.keep update your post
    AngularJS training in chennai | AngularJS training in anna nagar | AngularJS training in omr | AngularJS training in porur | AngularJS training in tambaram | AngularJS training in velachery

    ReplyDelete
  24. Good Post! Thank you so much for sharing this pretty post, it was so good to read and useful to improve my knowledge as updated one, keep blogging

    AWS training in Chennai

    AWS Online Training in Chennai

    AWS training in Bangalore

    AWS training in Hyderabad

    AWS training in Coimbatore

    AWS training

    ReplyDelete
  25. I like the helpful info you supply in your articles. I’ll bookmark your weblog and take a look at once more here regularly. I am relatively certain I will learn a lot of new stuff right here! Good luck for the following!
    sap training in chennai

    sap training in velachery

    azure training in chennai

    azure training in velachery

    cyber security course in chennai

    cyber security course in velachery

    ethical hacking course in chennai

    ethical hacking course in velachery

    ReplyDelete
  26. This article is really helpful for me. I am regular visitor to this blog. Share such kind of article more in future. Personally i like this article a lot and you can have a look at my services also: I was seriously search for a Salesforce training institutes in ameerpet which offer job assistance and Salesforce training institutes in Hyderabad who are providing certification material. It's worth to join Salesforce training institutes in India because of their real time projects material and 24x7 support from customer desk. You can easily find the best Salesforce training institutes in kukatpally kphb which are also a part of Pega training institutes in hyderabad. This is amazing to join Data science training institutes in ameerpet who are quire popular with Selenium training institutes in ameerpet and trending coureses like Java training institutes in ameerpet and data science related programming coures python training institutes in ameerpet If you want HCM course then this workday training institutes in ameerpet is best for you to get job on workday.

    ReplyDelete

Post a Comment

Popular posts from this blog

Spring Integration - Bulk processing Example

Pivotal Cloud Foundry (PCF) Integration with Elastic Cloud Storage (ECS)