Welcome to EMC Consulting Blogs

This is the third part in a series on Representational State Transfer (REST). The first part makes an attempt at a proper introduction to the principles of REST. The second part discusses about how these principles are applied on the Internet for human consumption (the Human Web) and how they can likewise be applied to computer systems (the Programmable Web). In this instalment, which I’ve broken up into two sub-parts, I want to share a fictional need for a service and then proceed to analyze the requirements and implement it in such a way that caters to both the Human and Programmable Webs. In the last sub-part we went over the requirements for the service and then made an attempt at a design. In this second sub-part, we’ll implement the design and take notes along the way.

While it is not required, I strongly suggest reading the other instalments first (at least the first sub-part that relates to this post) so that a lot of the design decisions I made make sense. It is my hope that you enjoy the ride as much I’m going to enjoy sharing it.

Also, you can find the entire source produced in this article here:

Season's Greetings Application Code

Part One Review

In the first part of this instalment, we had a mission statement and then set out to analyse and design the service in a RESTful way. This was our mission text:

We parsed out of the mission text some key things (e.g., human AND machine friendly) and also settled on a technology toolset (e.g., Java, XML). We then designed the service from both the perspective of the business component (the service itself) as well as from the perspective of the web application component that would host our service. We drew up some UML class diagrams for good measure, which we will revisit as we implement the service in this post. To get a full catch-up, read the first part fully. Then you’ll be ready to roll.

Our main use case was as follows:

Let’s make this a reality!

Service Implementation

Let’s start with the business service we will implement, so that we can have something to “serve” when it comes time to implement the web application bit. Here’s our design for the service:

We have five classes/interfaces to implement. We could start with the service, but that depends on the greeting model class, which in turn depends on the XML encoder/decoder. That has no visible dependencies, so let’s start there, XMLSerialiser:

1	package com.silvanolte.util;
2	
3	import com.thoughtworks.xstream.XStream;
4	
5	public class XMLSerialiser {
6	    
7	    private static final XStream XS = new XStream();
8	    
9	    public static String toXML(Object o) {
10	        return XS.toXML(o);
11	    }
12	
13	    public static Object fromXML(String xml) {
14	        return XS.fromXML(xml);
15	    }
16	
17	}

Implementing the to and from XML stuff is really a key bit to our service, and while I could break out Java’s XML APIs to do this parsing on my own in a generic way, I’ll delegate to a third-party library. In this case, I use XStream to handle this messy work. As you can see, this particular library is very easy, and out-of-the-box gives us everything we need.

With generic XML encoder/decoder done, let’s do the model object next, Greeting:

1	package com.silvanolte.model;
2	
3	import com.silvanolte.util.XMLSerialiser;
4	
5	public class Greeting {
6	
7	    public static Greeting fromXML(String xml) {
8	        return (Greeting) XMLSerialiser.fromXML(xml);
9	    }
10	
11	    private String message;
12	
13	    public Greeting(String message) {
14	        setMessage(message);
15	    }
16	
17	    public String getMessage() {
18	        return message;
19	    }
20	
21	    public void setMessage(String message) {
22	        this.message = message;
23	    }
24	
25	    @Override
26	    public String toString() {
27	        return message;
28	    }
29	
30	    public String toXML() {
31	        return XMLSerialiser.toXML(this);
32	    }
33	
34	}

I implement this as a simple JavaBean-like model class. The interesting bit to note is how we delegate the XML-related functions to our XML encoder/decoder (lines 7-9, 30-32). We’ve decoupled how we do the XML from the model itself while retaining a clean API to this functionality from right within the object. I also make the fromXML(String) : Greeting factory method static, so that it is bound to the class as opposed to a particular instance.

Let’s move on to the service interface now, GreetingService:

1	import com.silvanolte.model.Greeting;
2	
3	public interface GreetingService {
4	
5	    public Greeting getGreeting();
6	
7	    public Greeting getGreeting(String name);
8	
9	}

Simple service interface that exposes the functions we’re looking for. Three classes down and two implementations to go. Let’s do the core business one first, MyGreetingService:

1	package com.silvanolte.services.impl;
2	
3	import com.silvanolte.model.Greeting;
4	import com.silvanolte.services.GreetingService;
5	
6	public class MyGreetingService implements GreetingService {
7	
8	    public Greeting getGreeting() {
9	        return getGreeting(null);
10	    }
11	
12	    public Greeting getGreeting(String name) {
13	        if (name == null) {
14	            return new Greeting("Seasons' Greetings");
15	        } else {
16	            return new Greeting("Seasons' Greetings, " + name);
17	        }
18	    }
19	
20	}

This implementation is the one that does our actual greeting. We return a very cheery “Seasons’ Greetings” that becomes “Seasons’ Greetings, ” if a name is provided. Right. Now on to our last class, the remote service client, GreetingServiceClient:

1	package com.silvanolte.services.clients;
2	
3	import java.io.BufferedReader;
4	import java.io.IOException;
5	import java.io.InputStreamReader;
6	import java.net.URL;
7	import java.net.URLConnection;
8	import com.silvanolte.model.Greeting;
9	import com.silvanolte.services.GreetingService;
10	
11	public class GreetingServiceClient implements GreetingService {
12	
13	    private String serviceURI;
14	
15	    public GreetingServiceClient() {
16	        serviceURI = "http://localhost:8080/greeter-service/" +
17	                     "greeting.xml";
18	    }
19	
20	    public GreetingServiceClient(String URI) {
21	        serviceURI = URI;
22	    }
23	
24	    public Greeting getGreeting() {
25	        return getGreeting(null);
26	    }
27	
28	    public Greeting getGreeting(String name) {
29	        String resourceXML;
30	        try {
31	            resourceXML = getResourceXML(name);
32	        } catch (IOException e) {
33	            throw new IllegalStateException(e);
34	        }
35	        return (Greeting) Greeting.fromXML(resourceXML);
36	    }
37	
38	    private String getResourceXML(String name)
39	            throws IOException {
40	        String localURI = serviceURI;
41	        if (name != null) {
42	            localURI = localURI + "?name=" + name;
43	        }
44	
45	        URL url = new URL(localURI);
46	        URLConnection conn = url.openConnection();
47	        BufferedReader responseReader = new BufferedReader(
48	                new InputStreamReader(conn.getInputStream()));
49	        StringBuffer response = new StringBuffer();
50	        String line;
51	        while ((line = responseReader.readLine()) != null) {
52	            response.append(line);
53	        }
54	        responseReader.close();
55	
56	        return response.toString();
57	    }
58	
59	}

At 59 lines, this is our biggest class yet! Probably will prove to be the biggest class we have to do. Not surprising, from the standpoint of our discussion, this implementation has the most interesting things to note:

1. Lines 15-18, 20-22: I provide two constructors and a default URI. This gives the consumers of this implementation the freedom to supply their own URI, which may be useful.
2. Lines 28-36: The heart of my implementation simply gets the XML representation of the greeting using a private function, and uses the factory method on the Greeting object to satisfy the return value.
3. Lines 38-57: Arguably the most interesting, if not complex, bit. This is where I reach out over the web to get the XML that matters most to the implementation: the Greeting XML representation.
1. I noticed that I had not designed for how the name would be passed over the web, and made the decision at this time to pass it as HTTP Parameter (line 31). This is sufficient for now.
2. I utilised Java’s URL and URLConnection classes to make the reach over the web.

This completes the service side. As a reminder, you can find the entire source produced in this article here:

Season's Greetings Application Code

Web Application Implementation

Now we’re ready to build the web application bit. Before we start, let’s review our web application design:

According to this design we have three HTTP Servlets to implement. We also have to map the relevant URIs to the proper HTTP Servlets. Let’s start with the top-level Servlet, GreeterServlet:

1	package com.silvanolte.servlets;
2	
3	import java.io.IOException;
4	import javax.servlet.ServletException;
5	import javax.servlet.http.HttpServlet;
6	import javax.servlet.http.HttpServletRequest;
7	import javax.servlet.http.HttpServletResponse;
8	import com.silvanolte.model.Greeting;
9	import com.silvanolte.services.GreetingService;
10	import com.silvanolte.services.impl.MyGreetingService;
11	
12	public abstract class GreeterServlet extends HttpServlet {
13	    private static final long serialVersionUID = 1L;
14	
15	    private GreetingService greetingService;
16	    protected Greeting greeting;
17	
18	    public GreeterServlet() {
19	        greetingService = new MyGreetingService();
20	    }
21	
22	    protected void doGet(HttpServletRequest request,
23	            HttpServletResponse response) throws ServletException,
24	            IOException {
25	        greeting = greetingService.getGreeting(
26	                request.getParameter("name"));
27	    }
28	
29	}

First of all, you may notice I made this class abstract (Line 12). I did this because I only wanted to consolidate the business of getting the greeting (the model) with the express intent of letting subclasses handle how it routes the model to its respective views (in our case, HTML and XML).

Secondly, I account for any name that might have been provided to customise the greeting by checking for an HTTP parameter named “name” (Line 26).

Finally, I use the MyGreetingService implementation to get me the greeting I need. This works perfectly. But it is worth noting that I could have just as easily used GreetingServiceClient instead because it is a valid implementation of the GreetingService interface, allowing me to chain-link multiple HTTP calls, in theory. This is pretty powerful stuff.

Let’s move on to the HTML Servlet implementation, GreeterHTMLServlet:

1	package com.silvanolte.servlets;
2	
3	import java.io.IOException;
4	import javax.servlet.ServletException;
5	import javax.servlet.http.HttpServlet;
6	import javax.servlet.http.HttpServletRequest;
7	import javax.servlet.http.HttpServletResponse;
8	
9	public class GreeterHTMLServlet extends GreeterServlet {
10	    private static final long serialVersionUID = 1L;
11	
12	    public GreeterHTMLServlet() {
13	        super();
14	    }
15	
16	    protected void doGet(HttpServletRequest request,
17	            HttpServletResponse response) throws ServletException,
18	            IOException {
19	        super.doGet(request, response);
20	        request.setAttribute("greeting", greeting);
21	        getServletConfig().getServletContext().getRequestDispatcher(
22	                "/greeting.jsp").forward(request, response);
23	    }
24	
25	}

The most interesting things to note here are between lines 19 and 22. First, I make a call to the super class’ doGet() function, which is GreeterServlet’s doGet() function. And we know that this function puts together our model and places it in scope (through the protected local variable greeting). I then set the model on request scope (line 20) and finally forward the request to a JSP for generating the HTML view (lines 21-22). Let’s take a look now at that JSP, Greeting.jsp:

1	<%@ page language="java" 
2	         contentType="text/html; charset=ISO-8859-1"
3	         pageEncoding="ISO-8859-1"%>
4	<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
5	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
6	                      "http://www.w3.org/TR/html4/loose.dtd">
7	<html>
8	  <head>
9	    <meta http-equiv="Content-Type" 
10	          content="text/html; charset=ISO-8859-1">
11	    <title>Greeting Service</title>
12	  </head>
13	  <body>
14	
15	    <h1><c:out value="${greeting.message}"/></h1>
16	
17	  </body>
18	</html>

The interesting here to note is the use of JSP Expression Language (EL) on line 15 to pull the message out of the Greeting object. This is made possible because I put the Greeting object in request scope, and through the use of the core Java Server Tag Library (JSTL), which we define on line 4. This will generate the HTML part! Pretty exciting.

Let’s now XML Servlet implementation, GreeterXMLServlet:

1	package com.silvanolte.servlets;
2	
3	import java.io.IOException;
4	
5	import javax.servlet.ServletException;
6	import javax.servlet.http.HttpServlet;
7	import javax.servlet.http.HttpServletRequest;
8	import javax.servlet.http.HttpServletResponse;
9	
10	public class GreeterXMLServlet extends GreeterServlet {
11	    private static final long serialVersionUID = 1L;
12	
13	    public GreeterXMLServlet() {
14	        super();
15	    }
16	
17	    protected void doGet(HttpServletRequest request,
18	            HttpServletResponse response) throws ServletException,
19	            IOException {
20	        super.doGet(request, response);
21	        response.getOutputStream().print(greeting.toXML());
22	    }
23	
24	}

This is very similar to our HTML implementation with the key difference being on line 21. Instead of putting the model object on request scope and forwarding the request to a Java Server Page (something I could have done just the same), I decided to instead pass the XML representation straight to the response output stream. One good reason for doing it this way is that in relying on the service to define the XML, I’m freed of that implementation detail on the web application side. I can focus on the matter of receiving and processing a request, and delegate to the service the matter of creating an XML representation of the model object I get back from it.

The final bit is the mapping of URIs to HTTP Servlets. In a J2EE web application, this is done in a file called a web application description. It is named web.xml and while not in our design model, it is an implicit part of the application in that we’re implementing this in Java.

Below is the web.xml file for this web application:

1	<?xml version="1.0" encoding="UTF-8"?>
2	<web-app id="WebApp_ID" version="2.4"
3	    xmlns="http://java.sun.com/xml/ns/j2ee" 
4	    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5	    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
6	                    http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
7	    <display-name>greeter-service</display-name>
8	    <servlet>
9	        <description>
10	            A servlet that returns an XML representation
11	            of a greeting.
12	        </description>
13	        <display-name>GreeterXMLServlet</display-name>
14	        <servlet-name>GreeterXMLServlet</servlet-name>
15	        <servlet-class>
16	            com.silvanolte.servlets.GreeterXMLServlet
17	        </servlet-class>
18	    </servlet>
19	    <servlet>
20	        <description>
21	            A servlet that returns an HTML representation
22	            of a greeting.
23	        </description>
24	        <display-name>GreeterHTMLServlet</display-name>
25	        <servlet-name>GreeterHTMLServlet</servlet-name>
26	        <servlet-class>
27	            com.silvanolte.servlets.GreeterHTMLServlet
28	        </servlet-class>
29	    </servlet>
30	    <servlet-mapping>
31	        <servlet-name>GreeterXMLServlet</servlet-name>
32	        <url-pattern>/greeting.xml</url-pattern>
33	    </servlet-mapping>
34	    <servlet-mapping>
35	        <servlet-name>GreeterHTMLServlet</servlet-name>
36	        <url-pattern>/greeting.html</url-pattern>
37	    </servlet-mapping>
38	    <welcome-file-list>
39	        <welcome-file>greeting.html</welcome-file>
40	    </welcome-file-list>
41	</web-app>

The above may be a tad confusing to the non-Java crowd. The key lines to look at are lines 14-17, 25-28 and 30-37, which is where we name our HTTP Servlet classes and then map those Servlets (through their configured names) to URI patterns. Deploying our application with this web application descriptor will give us the results we desire.

This completes the web application side. As a reminder you can download all the relevant code here:

Season's Greetings Application Code

Putting it to the test

If you can and have the know-how, I strongly encourage you to download the source and deploy the Web Application Archive (WAR) file in the /greeter-web-application/build directory (greeter-service.war). This is already built for you, so you can follow along with these examples. You can also build the source, but will require some tinkering with the Ant build script (just don’t edit below the line I asked not to).

And if you have no idea what I’m talking about, don’t worry, it’s not required. Just read on. :)

I’ve built my code and deployed it to my web application server. To review, let’s remind ourselves of the use case we used to illustrate our high-level view of our service:

Let’s start with the web browser. I fire up Firefox and immediately type in the full URI to the HTML resource for a greeting:

http://localhost:8080/greeter-service/greeting.html

The result I get looks like this:

Fantastic! We got our greeting, just as we expected. If we look at the source of the HTML, this is what it looks like:

1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2	                      "http://www.w3.org/TR/html4/loose.dtd">
3	<html>
4	<head>
5	<meta http-equiv="Content-Type"
6	      content="text/html; charset=ISO-8859-1">
7	<title>Greeting Web Application</title>
8	</head>
9	<body>
10	
11	<h1>Seasons&#039; Greetings</h1>
12	
13	</body>
14	
15	</html>

Great stuff. This was generated by our Java Server Page, Greeting.jsp. We can compare line 11 of this generated HTML with line 15 of the Java Server Page code to see the relationship. The apostrophe at the end of the word ‘Seasons’ was automatically HTML-encoded for us, as well. Let’s try and add a name to the mix, see the personalized result:

It works! The Human Web now has a greeting service, albeit temporarily, that anybody with a browser, access to my network, and the right URI can access. If this were released on the World Wide Web, I could share the URI with anybody with Internet access and they would be able to get their own greeting.

Continuing to use Firefox, let’s request the XML representation of our resource, this time using the following URI:

http://localhost:8080/greeter-service/greeting.xml

The result I get looks like this:

This is a much different representation of essentially the same data (resource). Firefox has a built-in XML parser, and as such shows you the XML output our application returned, with a warning that there is no style information associated with it. This is fine, as we have no Extensible Stylesheet Language (XSL) file to provide the browser some guidance. After all, this is not meant for human consumption[1].

Let’s add a name to the URI to see the result, and make sure it works:

This is truly brilliant. I wrote my service code only once, and I’m sharing my data in two meaningful ways.

To drive this point home, let’s quickly implement and test that command-line Java application that I wanted to write to make use of the service client, GreeterServiceClient.

Rather than show the code, I’ll just jump straight into its utilisation. Definitely look at the source to see what I did on this Java application.

This is a screen shot of my console window. I change directories, set a classpath for my Java application and then run it, first without names then customised with names. I output the implementation I’m using to get the greeting. There are two quick things I want to bring to light here:

1. The output is the same, whether we use the local or remote implementation. There are some serious differences in how we get the data, but it’s still the same "stuff."
2. The remote implementation returns a "local" Greeting object, populated with data found on a "remote" server. I think this is the key to the beauty of REST. It focuses on resource state (data) and delegates the remainder to the client. In this case, the client gets the data, and creates an instance of the object on the client-side, giving a transparency that is seldom lost in the complex layers of frameworks and specifications found in the WS-I stack.

Conclusion

Well, in my third instalment I’ve done the longest one yet, splitting it into two parts. The upcoming ones won’t be as long, I assure you. But if you’ve hung in there with me, you’ve now been exposed to REST in both a theoretical and practical way. The way we think about data and how we share it is challenged when we consider a resource-oriented approach. Two representations can be completely different (in their format) and yet completely identical (in the resource state it represents) at the same time and in the same relationship. Seems illogical on the surface, but the power of this reality couples with the strengths of the Internet creates a foundation for truly accessible and scalable computing.

In my next post I will extend this example by supporting the HTTP POST method and introduce how we might expose a way to change the default greeting service behaviour, RESTfully. I will also add a Ruby-based client to our library of service implementations, to open our service to all those Ruby power users out there. And as I look to close out the series, we will look at implementing the rest of the HTTP methods and investigate some of the frameworks available today to help make your applications RESTfully beautiful.

Until next time!

[1] This is the key bit of REST! The ability to have multiple representations of the same data through the same medium is the core to REST. Back to article