{"id":735,"date":"2011-12-23T16:21:00","date_gmt":"2011-12-23T16:21:00","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/2012\/10\/develop-restful-web-services-using-spring-mvc.html"},"modified":"2012-10-21T20:48:09","modified_gmt":"2012-10-21T20:48:09","slug":"develop-restful-web-services-using","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2011\/12\/develop-restful-web-services-using.html","title":{"rendered":"Develop Restful web services using Spring MVC"},"content":{"rendered":"
REST INTRODUCTION<\/strong><\/p>\n
\n
\n

From Wikipedia: REST-style<\/strong> architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed.<\/p>\n<\/blockquote>\n<\/div>\n

\nAs you have read the most important thing in Rest <\/strong>architecture is the existance of a resource. This resource  can be anything (typically required information requested by client) that can be identified with a global identifier (URI<\/i> in case of HTTP<\/i>). In order to manipulate these resources, client communicates using standard interfaces (like HTTP<\/i>) and exchange representations of these resources (using HTML<\/i>, XML<\/i>, …).<\/div>\n
\n<\/div>\n
Note that Rest<\/strong> does not force you to use any specific network protocol nor how resources are identified.<\/p>\n

For those who have never read about Rest<\/strong> this description of Rest<\/strong> architecture could seem something strange and bit complicated. <\/div>\n

\n<\/div>\n
A RESTful<\/strong> web service is a simple web service implemented using HTTP<\/i> and the principles of REST<\/strong>. URI<\/i> is defined as global identified, communication interface is HTTP and resource representation can be any valid Internet media type like JSON<\/i>, XML<\/i> or YAML<\/i>. The set of operations that can be executed to resources depend on HTTP<\/i> Methods and are (GET<\/i> – retrieving\/listing, PUT<\/i> – replacing\/updating, POST<\/i> – creating and DELETE<\/i> – deleting).<\/div>\n
\n<\/div>\n
\n
HANDS ON WORK<\/strong><\/div>\n
\n<\/div>\n
\n
Let’s create our first Rest<\/strong> application with help of Spring MVC<\/strong>. Imagine an application that has a database of manga characters, and you want to provide a Rest <\/strong>interface so clients can retrieve characters following a RESTful <\/strong>strategy.<\/div>\n<\/div>\n
\n<\/div>\n
\n
First thing to do is identify the resource. In this case it is easy, “a character<\/i>“. Next step is finding a URI<\/i> that determines unequivocally a character. Easy too de facto<\/i> rule can be applied here. This rule suggests that a unique URI<\/i> can be <host>\/<applicationname>\/<resourceName>s\/<id> in our case to return (GET<\/i>) character with id 1 the URI would be “http:\/\/localhost:8080\/RestServer\/characters\/1<\/i>“. If no identifier is present all characters should be retrieved. If instead of GET<\/i>, POST<\/i> is used, a character with id “1” would be inserted. And finally decide which Internet media type<\/i> is required, in this case doesn’t matter because we are implementing both client and server so initially XML<\/i> will be used.<\/div>\n<\/div>\n
\n<\/div>\n
CODING<\/strong>
\nLet’s start with a simple Spring MVC<\/strong> application created with Spring MVC<\/strong> template. Not much secret here, you will have a servlet-context.xml<\/i> where component-scan<\/i>, annotation-driven<\/i> and InternalResourceViewResolver<\/i> are registered.<\/p>\n
<?xml version=\"1.0\" encoding=\"UTF-8\" ?> \r\n<beans:beans xmlns=\"http:\/\/www.springframework.org\/schema\/mvc\" xmlns:xsi=\"http:\/\/www.w3.org\/2001\/XMLSchema-instance\" xmlns:beans=\"http:\/\/www.springframework.org\/schema\/beans\" 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\/util http:\/\/www.springframework.org\/schema\/util\/spring-util-3.0.xsd http:\/\/www.springframework.org\/schema\/context http:\/\/www.springframework.org\/schema\/context\/spring-context-3.0.xsd\">\r\n <!--  DispatcherServlet Context: defines this servlet's request-processing \r\n  infrastructure \r\n  --> \r\n <!--  Enables the Spring MVC @Controller programming model \r\n  --> \r\n\r\n  <annotation-driven \/> \r\n\r\n <!--  Resolves views selected for rendering by @Controllers to .jsp resources \r\n  in the \/WEB-INF\/views directory \r\n  --> \r\n\r\n <beans:bean class=\"org.springframework.web.servlet.view.InternalResourceViewResolver\">\r\n  <beans:property name=\"prefix\" value=\"\/WEB-INF\/views\/\" \/> \r\n  <beans:property name=\"suffix\" value=\".jsp\" \/> \r\n <\/beans:bean>\r\n\r\n  <context:component-scan base-package=\"org.springframework.rest\" \/> \r\n<\/beans:beans>\r\n<\/pre>\n
Next step is defining Character<\/i> class. A simple POJO <\/i>with four attributes. Class is converted to its XML representation<\/i> using Jaxb <\/i>annotation.  Jaxb <\/i>allows developers to map Java <\/i>classes to XML <\/i>representations and viceversa.
 
<\/div> <\/div><\/p>\n
package org.springframework.rest;\r\n\r\nimport java.net.URL;\r\n\r\nimport org.codehaus.jackson.annotate.JsonAutoDetect;\r\n\r\n\r\n@XmlRootElement\r\npublic final class Character {\r\n\r\n private  int id;\r\n private  String name;\r\n private  boolean isHuman;\r\n private URL characterUrl;\r\n\r\n protected Character() {\r\n\r\n }\r\n\r\n public Character(int id, String name, boolean isHuman, URL characterUrl) {\r\n  super();\r\n  this.id = id;\r\n  this.name = name;\r\n  this.isHuman = isHuman;\r\n  this.characterUrl = characterUrl;\r\n }\r\n\r\n\r\n\r\n public int getId() {\r\n  return id;\r\n }\r\n\r\n public void setId(int id) {\r\n  this.id = id;\r\n }\r\n\r\n public String getName() {\r\n  return name;\r\n }\r\n\r\n public void setName(String name) {\r\n  this.name = name;\r\n }\r\n\r\n public boolean isHuman() {\r\n  return isHuman;\r\n }\r\n\r\n public void setHuman(boolean isHuman) {\r\n  this.isHuman = isHuman;\r\n }\r\n\r\n\r\n public URL getCharacterUrl() {\r\n  return characterUrl;\r\n }\r\n\r\n public void setCharacterUrl(URL characterUrl) {\r\n  this.characterUrl = characterUrl;\r\n }\r\n\r\n @Override\r\n public int hashCode() {\r\n  final int prime = 31;\r\n  int result = 1;\r\n  result = prime * result + id;\r\n  return result;\r\n }\r\n\r\n @Override\r\n public boolean equals(Object obj) {\r\n  if (this == obj)\r\n   return true;\r\n  if (obj == null)\r\n   return false;\r\n  if (getClass() != obj.getClass())\r\n   return false;\r\n  Character other = (Character) obj;\r\n  if (id != other.id)\r\n   return false;\r\n  return true;\r\n }\r\n\r\n\r\n}\r\n<\/pre>\n
And finally the most important class in Spring MVC<\/strong>, “The Controller<\/i>“. Controller will be the responsible of implementing required operations of Character <\/i>resource. In current case only GET <\/i>is implemented, the other operations would be similar. Let’s see the code:<\/p>\n
@Controller\r\npublic class HomeController {\r\n\r\n\r\n private static final Map<Integer, Character> characters = new HashMap<Integer, Character>();\r\n\r\n static {\r\n  try {\r\n   characters.put(1, new Character(1, \"Totoro\", false, new URL(\"http:\/\/animeonly.org\/albums\/VISINAUJI\/EGIO\/fourth\/Mon-Voisin-Totoro\/normal_totoro_001.jpg\")));\r\n   characters.put(2, new Character(2, \"Satsuki Kusakabe\", true, new URL(\"http:\/\/profile.ak.fbcdn.net\/hprofile-ak-ash2\/48980_1802552968_7286_n.jpg\")));\r\n   characters.put(3, new Character(3, \"Therru\", false, new URL(\"http:\/\/28.media.tumblr.com\/tumblr_lj4ctjKA8Y1qdvyqpo1_400.jpg\")));\r\n  } catch (MalformedURLException e) {\r\n   e.printStackTrace();\r\n  }\r\n }\r\n\r\n \/**\r\n  * Simply selects the home view to render by returning its name.\r\n  *\/\r\n @RequestMapping(value = \"\/characters\/{characterId}\", method = RequestMethod.GET)\r\n @ResponseBody\r\n public Character findCharacter(@PathVariable int characterId) {\r\n  return characters.get(characterId);\r\n\r\n\r\n }\r\n\r\n}\r\n<\/pre>\n
First part is a map where all characters are stored. I have used this approach to not focus in data access. Then findCharacter <\/i>method that is called when URI <\/i>is \/characters\/{characterId<\/i>}. This is a URI <\/i>template and is a URI<\/i>-like string, containing one or more variable names, which can be accessed using @PathVariable<\/i> annotation. So when you are accessing to \/characters\/1<\/i> parameter characterId<\/i> is bound to 1.<\/p>\n
Last important part is @ResponseBody <\/i>annotation. This annotation can be put on a method and indicates that the return type should be written straight to the HTTP <\/i>response body, and not placed in a Model<\/i>, or interpreted as a view name as standard behaviour of Spring MVC<\/strong>. So findCharacter <\/i>method returns a Character <\/i>object.<\/p>\n
And that’s all if you execute this code, and for example you enter URI http:\/\/localhost:8080\/RestServer\/characters\/1<\/i> the output (using RestClient UI<\/a>) will be:<\/p>\n
<\/a><\/div>\n
And now is when you are wondering, \u00bfIf I am returning a Character <\/i>object and output is a XML<\/i>, where is conversion between object and XML<\/i>? So easy, let me introduce a new concept: HttpMessageConverters<\/strong>. HttpMessageConverter <\/strong>is responsible for converting from HTTP<\/i> request message to an object and converting from an object to HTTP <\/i>response body. Next HttpMessageConverters <\/strong>are registered by default:<\/div>\n<\/div>\n
\n<\/div>\n
\n
 <\/span>– ByteArrayHttpMessageConverter<\/i><\/div>\n
 <\/span>– StringHttpMessageConverter<\/i><\/div>\n
 <\/span>– ResourceHttpMessageConverter<\/i><\/div>\n
 <\/span>– SourceHttpMessageConverter<\/i><\/div>\n
 <\/span>– XmlAwareHttpMessageConverter<\/i><\/div>\n
 <\/span>– Jaxb2RootElementHttpMessageConverter<\/i><\/div>\n
 <\/span>– MappingJacksonHttpMessageConverter<\/i><\/div>\n
\n<\/div>\n
\n
So now you understand why works perfectly. When you are returning Character <\/i>instance, Jaxb2RootElementHttpMessageConverter <\/strong>using canWrite <\/i>method checks if class contains XmlRootElement <\/i>annotation. If class is annotated, write method is called. In this case Jaxb <\/i>marshaller is called, and XML <\/i>is returned. Same from XML <\/i>to object but using Jaxb <\/i>unmarshaller class.<\/div>\n
\n<\/div>\n
So easy, no complicated configurations, no complicated mappings, no unclear code, and you only need to worry about your model objects, not in conversion. But let me introduce one change. Now instead of returning XML <\/i>we want to return JSON<\/i>.<\/div>\n
\n<\/div>\n
Change could not be easier, add Jackson<\/i> library to pom.xml<\/i> and change @XmlRootElement<\/i> to @JsonAutoDetect<\/i>. And now MappingJacksonHttpMessageConverter <\/strong>will handle this object and will transform Character <\/i>instance to JSON <\/i>protocol using Jackson<\/i> library. Only changing one line of code!!!<\/div>\n
\n<\/div>\n
And now output will be:<\/p>\n
<\/a><\/div>\n
CONCLUSIONS<\/strong><\/p>\n
Of course this is a very simple application with only one operation, but it gives you an idea of how to develop Restful <\/strong>web services using Spring MVC<\/strong>. It is a matter of time of writing all your required operations using same approach that I have used with GET<\/strong>.<\/p>\n
Arriving at this point I think that all of us have arrived to same conclusion. Annotations are really really powerful, and Spring MVC<\/strong> fits perfectly for developing RESTful<\/strong> web<\/strong> services.<\/p>\n
See you next time…<\/p>\n
Download Code.<\/a><\/p>\n
Reference: <\/i><\/strong>Develop Restful web services using Spring MVC<\/a> from our JCG partner<\/a> Alex Soto at the One Jar To Rule Them All<\/a> blog.<\/p>\n
Related Articles :<\/i><\/strong><\/p>\n