wwerner's blog

So, what is that Restlet thing anyway? Basically, Restlet is a library that assists you to in building REST style applications ⁴. Restlet implements many core concepts from Roy T. Fieldings dissertation ⁵ directly, so if you are familiar with the REST architectural style, you’ll recognize many of the base classes of the API immediately.

The most notable concept for our purpose is the uniform interface. It allows components to to be assembled arbitrarily without revealing their internal structure to clients. Clients don’t need to realize to which kind of component they are talking to, this allows the server components to change without breaking existing clients. Real life examples are Pipes on *nix systems and – of course – the web. Your browser did not notice to which components it was talking to when you were loading this page. Chances are that there are multiple caches, a proxy and a virtual host between you and the physical storage location of this content. The browser doesn’t know about this; all it cares about is that its GET request got handled. And all components along the way know how to do that: They have a uniform interface ⁶.

Restlet allows for building both client and server applications. We’ll concentrate on the server side in this tutorial. The figures below are actually annotated copies from the Restlet documentation ³, filtered to exclude all elements we won’t use in this tutorial ⁸

Since all the the classes that implement the UniformInterface know how to handle HTTP requests, we are able to assemble them very flexibly. Great, this promotes loose coupling in our application. I was tempted to include a matrix of which combinations are valid, but that is beside the point. Better think of it as a variation of the classic composite pattern ⁹, like this: “Everything is a Restlet (Component). There are special Restlets that can contain other Restlets (Composites).”

While the Restlet derived classes are mostly used to define the hierarchical  structure and the management of the application, the actual business data is served and updated by Resources. Resources are not part of the Restlet inheritance hierarchy but are derived from a common UniformResource base class. Uniform? Heard that before? Yes, Resources also know how to handle HTTP requests. They are the targets of a hypertext reference/URI.

To go back to the Composite pattern reference, we now also know what the Leafs of the composite pattern are: “Everything is a Restlet (Component). There are special Restlets that can contain other Restlets (Composites). ServerResources are Leafs.”

Given I understood everything correctly, I think the Restlet API could make these points more intuitive by adding a common base class for composite Restlets and by including UniformResource as leafs into the Component inheritance hierarchy. But I do not claim to have any authority on that topic.

• The server must able to issue a greeting
• There needs to be a controllable list of approved greetings
• The current greeting must be selectable by a administrator
• An administrator needs the possibility to add and remove greetings from the list
• The current list contents must by visible to the administrator
• For the sake of the examples, a greeting in the list needs to have a mnemonic by which it can be found. The list of greetings is actually a map of mnemonics and greetings.

As want to control the allowed greeting values, we’ll have to remove the @Put method in GreetingResource to disallow rouge write access.

We modify GreetingStorage to hold a map of valid greetings and allows us to add and remove greetings.

1. It displays the current greeting map content a single greeting (list())
2. It adds a given greeting to the list (set(), via POST & a “greeting” parameter )
3. It removes a given greeting from the list (remove())

The interesting part is how the application will be assembled: We first create a component and attach an HTTP server to it. Then we create an application containing our management section. This is – for the time being – only a container that creates a new namespace for the administration part . To this application, we attach a Router that is configured to route the requests to GreetingListResource and get the mnemonic part of the URIs.

As in the last post, the complete code is available on github ¹³.

• http://localhost:8182/tutorial2/manage/list
• http://localhost:8182/tutorial2/manage/list/default
• POST a parameter called “greeting” to http://localhost:8182/tutorial2/manage/list/newGreeting
• Show the list again

You’ll have noticed that the the component local variable was turned into a member variable and that a second method, stop() was introduced. Analogous to start() the stop() method of the Activator is called whenever the OSGi runtime stops the bundle.

I did this to be able to hot deploy the bundle within the running OSGi framework without having to restart the server. Sure, if I start the application from the IDE I run it in debug mode, but this won’t help when I make changes to the activator. Remember, the start() method is only called when the bundle is first loaded. As most of the application assembly currently happens there, we’d still have to restart the whole framework for the changes to be picked up.

OSGi to the rescue! One of OSGi core features is the ability to manage (start, stop, install, update) individual bundles within a running framework. OSGi describes management agents that are able to do so. Equinox ships with a management agent as a console. Let’s see how we can use that in our example.

First, we need to tell our launch config to enable the management console.

Start the application in debug mode. In the console, you’ll see an “osgi>” prompt now. Type “ss” (for short status) and hit enter. Hey, there is our bundle.

Remember the ID for subsequent commands. You can also use the full name of the bundle, but we’re lazy, right¹⁴?

Let’s suppose you want to change the management URL from “manage” to “admin” ^{15 16}.

So you change that piece of code  and check the new URL. And receive a lovely 404 because no one called the start method in our Activator. So let’s use the management console to restart the bundle: We remembered the bundle ID and just call “stop <ID>” and “start <ID>” in sequence. Now you also see the purpose of the stop() method addition above. We basically attached our components life cycle to the one of our bundle.

Hint: Use the “help” command in the console to see if there is a shorter way to do the restart.

Now point your browser to the new URL (http://localhost:8182/tutorial2/admin/list) and be utterly astonished. It works.

If you want to dive in a little deeper into Restlet, check out the great tutorials on the Restlet home page^{17 18 19}. Some of this will be familiar. A great next step would be to learn what different Representations of a Resource are and how the content types are negotiated.

The next post will introduce equinox’ extension point/extension paradigm and remove the concrete application assembly from the Activator by using it. We’ll also tackle the hidden requirement that we didn’t implement. Can you find it?

A last word of warning: Now that you know how to create those nice looking URLs, don’t build a product and go around advertising your RESTful API, or the holy wrath of Roy T. Fielding will consume your soul ²⁰. You (and I, for that matter) still have a lot to learn. Use the term “CRUD over HTTP” for now, even if it gives you less buzz. Seriously.

I came across the headline “Tutorials should foster thinking” in a smashingmag post yesterday. Did this tutorial make you think? Leave a comment.