Building RESTful Web Apps with Groovy and Restlet, Part 1: Up and Running

Here at Arc90, we love REST. We’ve implemented RESTful web apps using ColdFusion, Java, .NET/C#, and PHP. We’re big fans of Restlet, a Java REST framework. I’ve also recently started experimenting with Groovy, “an agile dynamic language for the Java Platform,” and so far I’m liking it.

So it’s a no-brainer for us to put Groovy and Restlet together and see what happens. So far, I like what I see. That said, it’ll be tough to convince some of my PHP-loving and Pythonistic colleagues to even consider Groovy, given its Java roots. Some of them fairly shudder when they hear those two syllables “ja-va”. Ooh, scary.

This blog series will be my attempt to present how Groovy and Restlet together create a compelling platform for rapid RESTful web application development.

So let’s get started with the classic Hello world!

Prerequisites

Before we get started, two prerequisites:

1. Java 1.5 or newer – download (I used 1.5.0_13)
2. Groovy 1.5 or newer – download (I used 1.5.6)

Setup

1. Download the latest version of Restlet 1.1 – link – and extract it anywhere
2. Create a folder named restfulapp
3. Create a file named restfulapp.groovy
4. Copy two files from the Restlet distribution’s lib folder to restfulapp:
   • org.restlet.jar
   • com.noelios.restlet.jar

I’m specifying Restlet 1.1, which hasn’t yet hit final release, as opposed to the stable 1.0 branch, because it has a built-in HTTP server and client, which makes it really easy to just dive right into development and have something up and running quickly. These built in HTTP components aren’t production-class, but they’re very convenient for our purposes here.

The Code

Before we get into the code, please note: this code does not demonstrate best practices, and is not production ready; at this point I just want to establish basic concepts.

restfulapp.groovy

Copy the following code into restfulapp.groovy:

#!/usr/bin/env groovy -classpath org.restlet.jar:com.noelios.restlet.jar
import org.restlet.*
import org.restlet.data.*
// RequestHandler will handle all of our requests
class RequestHandler extends Restlet
{
// handle() is called by the framework whenever there's a HTTP request
def void handle(Request request, Response response)
{
/* The only method that's allowed is GET, so check it -- if it's GET,
return a representation, and the default status will be returned,
which is 200 OK. If not, set the response status to an error. */
if (request.method == Method.GET)
{
/* handle() returns void, for reasons that will become clear
later. The way to output content is modify the passed-in response
by setting the Entity of the response. Restlet refers to the
Representation as an "entity"; I'm actually not 100% sure why. */
response.setEntity("Hello, world!", MediaType.TEXT_PLAIN)
}
else
{
// The request method is not GET, so set an error response status
response.setStatus(Status.CLIENT_ERROR_METHOD_NOT_ALLOWED)
response.setAllowedMethods([Method.GET] as Set)
}
}
}
/* Create a new HTTP Server on port 3000, pass it a new instance of RequestHandler,
to which it will pass all incoming Requests, and start it. */
new Server(Protocol.HTTP, 3000, new RequestHandler()).start()

I’m hoping this code illustrates some of the great aspects of Restlet and Groovy. Restlet’s class model is clear and intuitive because it was designed specifically to model REST concepts, so a server is a Server, a method is a Method, a Request is a request, etc. And because this app is a Groovy script, we can use inline class definitions, and the syntax is nice and clean and easy.

I particularly like that Groovy maps the == operator to “value equality” as opposed to “identity equality” as in Java. The Java equivalent of line 16 would be:

if (request.getMethod().equals(Method.GET))

This also illustrates Groovy’s automatic getter referencing: to retrieve the method of the request, in Groovy I can use the syntax request.method, and Groovy automatically converts it into request.getMethod(). Nice!

Up and Running

Unices

$ chmod +x restfulapp.groovy
$ ./restfulapp.groovy

Windows

Launch a command prompt window, navigate to restfulapp, and run the command:

groovy -classpath org.restlet.jar;com.noelios.restlet.jar restfulapp.groovy

Test!

If you have cURL installed, you can run a quick ad-hoc test with the following command:

curl -v http://localhost:3000

But Groovy can make unit testing really easy:

Create a new file named testfulapp.groovy and copy the following code into it:

#!/usr/bin/env groovy -classpath org.restlet.jar:com.noelios.restlet.jar
import org.restlet.*
import org.restlet.data.*
client = new Client(Protocol.HTTP)
response = client.get("http://localhost:3000/")
assert response.status.code == 200
assert response.entity.mediaType.equals(MediaType.TEXT_PLAIN, true)
assert response.entity.size == 13
assert response.entity.text == "Hello, world!"
println "\nAll tests passed successfully!\n"

Open a new command prompt window, alongside the one already running restfulapp.groovy, and run testfulapp.groovy using the same steps outlined above for restfulapp.groovy for your OS. If all goes well, you should see “All tests passed successfully!” as the result!

Performance

Just for fun, if you’ve got a copy of ab installed:

ab -c 2 -t 10 http://localhost:3000/

Any numbers you see from ab can only be compared to your own, because everyone’s hardware and software varies, but it’s still fun to try pounding on your code and see what happens. I got 713 requests per second on my 2.2 GHz Santa Rosa Core 2 Duo MacBook, on OS X 10.5.3 and Java 1.5.0_13 – not bad!

That’s all, folks!

And that’s all for now. I hope this has been interesting and/or informative. I’d love to hear some feedback from readers: has this article made you interested in learning more about Groovy and/or Restlet?

Coming soon: Part 2: Resources.

Update, June 13th: Just published Part 2: Resources.