So in between some really long days at work, the usual before release panic and regression defects. I finally completed a simple RESTFul example, before getting into the details, here are a couple facts about RESTFul services.
- REST stands for Representational State Transfer.
- Each unique URL is a representation of some object.
- You can get the contents of that object using an HTTP GET.
- You may use a POST, PUT, or DELETE to modify the object.
- It is not necessary to use XML as a data format, so for small amounts of data it can be significantly lighter on bandwidth.
- REST as a protocol does not define any form of message envelope.
- REST takes advantage of HTTP caches. (A cache can't to do anything a POST; but they can cache GETs and expire those entries based on PUTs and DELETEs.).
- The Sun specification for RESTFul webservices can be found atJAX-RS
- Spring does not directly support or implement the JAX-RS spec but instead RESTful functionality is added to feature Spring MVC.
As with my other examples all the source code, config and POM files are available in SVN
As we are exposing information via HTTP this is going to be a web project. I won't be going into details of compiling and deploying a web application, but will go through all the required parts
Starting with the web.xml:
The DispatcherServlet will receive the request it will then, based on the servlet mapping
go looking for "Spring3RESTFul-servlet.xml" which in turn defines the controller and view (which are dynamically searched for and created):
The component-scan in the application context above will be used to automatically pick up our @Controller. If you go to /app/users/Bob, the getUser method is executed and their respective name is passed through as a parameter. The Spring JaxB 2 marshaller will be used to marshall the User object in and out of XML. Any of the OXM marshallers can be used, I just simply prefer JaxB.
Note: You really should not have a horrible static map containing state within a controller (like I do below), I am only doing it now because this is an example, and I want to keep it simple and not digress into a full blown application. If I have time over the next week or so, I'll remove that map of data and just create an embedded DB or something.
You can view the results in your browser by simply going to the url. I am using weblogic, so mine looks like "http://localhost:7001/Spring3RESTFul-1/app/users/Mary" but depending on your deployment it could differ as long as you add "/app/users/Mary" to your context root you should get the following displayed. (if you are using firefox)
However, chances are you are not writing this to view some XML in a browser but rather to get or manipulate information from one system or component to another. For this I created a little client, this client uses Springs' RestTemplate which is autowired and lets me access the HTTP functions:
Quote from Spring blog:
DELETE delete(String, String...)
GET getForObject(String, Class, String...)
HEAD headForHeaders(String, String...)
OPTIONS optionsForAllow(String, String...)
POST postForLocation(String, Object, String...)
PUT put(String, Object, String...)
This example only uses getForObject, postForObject, put and delete for the moment, so just the normal CRUD operations.
Now to use the above client I have a test application context injecting the RestTemplate and a test case preforming the create, retrieve, update and delete.
Note:Because I just wanted to create 1 project for this example I have included the following, just so that you can compile and deploy and then run the test case... but ever adding this to a actual project POM file should be grounds for a good beating.
Lastly actual test case. Deploy the war file created by the POM to the web / application server of your choice before running the below:
And that is it... a Simple CRUD RESTFul Webservice example with Spring 3.