• (German) A piece on the Equinox OSGi Console, basically the same as in an earlier post here. Published in eclipse Magazin 2.11. HTML, PDF
• (German) Devising an RESTful architecture based on OSGi & Restlet using e-mobility charging station software as business case. Published in eclipse Magazin 6.11. HTML, PDF
• A review on PostGIS in Action on dzone.

<INSERT 2012 WRITE-MORE RESOLUTION HERE>

Contents

1. Preparation
2. The Model
3. First Service
4. Wiring it up
5. Application
6. Take it for a test drive
7. Some data
8. More Services
9. Reading is always easy...
10. I rest my case

The complete source code is available on github. There is one branch for each step so you can easily switch back and forth and compare your state with the expected one.

The POM defines a number of dependencies. The most notable ones are CXF ¹, Jackson ² and Spring ³.

Run the following commands on the shell.

This will create the eclipse project we’ll be working on. I put in a little hack using the antrun plugin to create the source folders that would have been there if we started from an archetype. I’m pretty sure there is a better way to do this, please leave a pointer if you know.

CXF comes with quite a load of dependencies of it’s own, so you might want to get a coffee⁴ while maven downloads the internets.

After mvn finished, you should have the same file structure as in this branch: https://github.com/wwerner/JAXRSTutorial/tree/stage2

Import the created project into your workspace using Import->Existing Projects. The project should look like this in the project explorer view:

We’ll put all of this in a new package in our project: net.wolfgangwerner.tutorial.jaxrs.model in src/main/java.

Now, the only thing we have to do to expose this method is to add some JAX-RS annotations, @GET, which tells the runtime that this method should be called on GET requests and @Path which defines the URI (template) for which this method should be called. Additionally, we’ll add @Produces to make explicit which content type we are returning.

Anyway, I’d like to do it a little different⁶: We’ll use Spring IoC with the JAX-RS configuration namespace provided by CXF to define an HTTP server and publish our resource.

Create the file application-context.xml for Spring in src/main/resources and put in the following content.

Now what’s in there? First interesting thing is the declaration of the jaxrs namespace from CXF: xmlns:jaxrs=”http://cxf.apache.org/jaxrs. Then we define two beans, one for our service class and one for the jackson provider that will be used to render JSON representations.

The next part configures an HTTP server (CXF comes with jetty⁷) to run on localhost port 9001. We tell the runtime to look for services in the service bean we defined earlier and we register the jackson JSON provider with this server.

The application does nothing more than to look for a spring xml configuration file on the classpath and to start the configured context.

Select the Application class and choose Run as.. -> Java Application⁸

The console output should tell you that spring wired the dependencies, jetty started and is listensing on port 9001 as you told it to in the application context.

If  you followed my earlier tutorials, you’ll know Poster⁹, a firefox addon to make HTTP requests. If you don’t have it, get it or  use the HTTP speaking tool of your choice instead ¹⁰.

Use Poster to GET http://localhost:9001/hello . Remember we defined the server port in application-context.xml and path via the @Path annotation in MovieService.

Let’s try another thing: We can ask our service which kinds of interaction it supports using the OPTIONS HTTP verb¹¹.

This tells us that we can execute GET, HEAD and OPTIONS requests on our /hello URL:

This is what it would look like with cURL:

R

First we create a couple of actors, then we associate them with the movie using the cast map.

Note that we added an URL parameter {id} to the @Path annotation. We also added the @PathParam annotation to the id parameter in our method¹².

That’s the result¹³:

We got JSON, as this is the first type defined in our @Produces annotation and the client did not send any preferences. Let’s add a request header that says ‘I’d rather take XML’¹⁴.

This returns … … … an error? Correct. A kind of cryptic one as well:

No message body writer has been found for response class Movie.

This means that the jax-rs runtime did not find anything to serialize our Movie. Jackson, the JSON processor is kinda smart, it just uses reflection to render JSON. But for XML, we need to Do Stuff™. How do we get that body writer? We don’t need to. We can just use JAXB annotations in our model to link our data to an XML representation. The first thing to do is to add the @XmlRootElement annotation on both our model classes.

If you run this, you might note that the cast may be displayed before the title. That’s fugly. Add@XmlType(propOrder={“title”, “cast”})  to the movie class, restart the application and you are good. The nice thing about the JAXB bindings is that they are also evaluated by jackson. Add the annotation @XmlElement(name=”who”) to the getName() method of Actor and see what happens.

Note that the “name” element changed in both representations.

To see which data we have stored on the server, we’ll also add a new service that returns all movies. Note that (typed) collections are handled transparently as well.

To make it a little more interesting, we return a useful response that tells us which resource has been created¹⁵.

Just copy either the JSON or XML representation and POST it to the /movies URL using a new id. This will create a new movie and return it’s URL. You can also GET /movies to see a complete list of movies available.

Two weeks before writing this post I gave a talk at the company I work with¹⁶ about REST and common REST misconceptions that also featured a live hacking session with the stuff you just read. Then I thought that I could reuse it for a blog. Then I went to Eclipse Summit Europe¹⁷ where @doug_clarke used JAX-RS in his talk, then @vogella published a tutorial on JAX-RS as well¹⁸.

I like to believe that it is an interesting topic more than I like to believe it is grossly redundant. Feel free to disagree, here’s my take on it anyway. As a side note, it’s actually only 89 lines of java code. That is pretty lean, I’d say. You can get each and every of these lines here. Awesome, isn’t it?

Also note that as we speak, a new version of the JAX-RS/JSR311 specification is proposed here.

I’ll follow up on this post with adding JPA persistence to our movie store. Stay tuned if you are interested.

As bedtime candy, here are some of the slides¹⁹ I used in my talk.

Btw., we are looking for java developers. Please feel free to contact me if you are interested.

Contents

1. Preparation
2. Test First
3. Monkey See, ...
4. ... Monkey Do
5. Strange Loops
6. Conclusion

Now start eclipse, create a new workspace and go to the workbench.

Open the console view (Alt-Shift-Q,Q) and select “OSGi console” from the view menu.  You now have an OSGi console that allows you to interact with the running eclipse³.

Type “help” to get a list of available commands. You should do that even if you are a eclipse veteran, the list of available commands has grown considerably during the last years. There are commands to start/stop/install/refresh bundles, to view registered services, to configure runtime properties, to query the extension registry, to start and stop equinox applications and enable and disable components.

We also need some piece of code to let us run our tests. Luckily, JUnit provides a simple API for that⁴.

Instead of repeating this⁷, I’d rather show you how to figure it out for yourself. Reading code is an excellent way to learn⁸.

First, we need an entry point, a piece of code we know that has something to do with the console. So what do we know? Well, there is a console view, let’s go hunting for it’s implementation. To make sure that our searches include the code from the platform plug-ins, we will add them to the Java search.  Helios has a handy new button in the Plug-Ins view for that. ⁹

Fire up the search dialog ¹⁰, select the Plug-in Search tab, enter “org.eclipse.ui.views” as search string and select “Search for-> Extension Point”, “Limit to -> References” and “External Scope -> All”.

This search gives us 28 matches. One match is the one we are looking for: org.eclipse.ui.console.

Let’s open the declaration and switch over to the extensions tab. We can see the contribution the console view we were looking for, but also something that looks even more promising: An extension point called “org.eclipse.ui.console.consoleFactories”. Let’s see who contributes to this extension point. Choose “Find References” from its context menu.

Only four matches. I think we can rule out the one in team.cvs and debug.ui.  We’ll find what we are looking for in the org.eclipse.pde.ui bundle¹¹.

The contribution contains the implementation class, so we open this class next. Copy the qualified name of the class, press Ctrl-Shift-T and paste the class name.

In the console factory, we find that a new console is instantiated in the getConsole() method. Let’s open the implementation by Ctrl-Click on the class name.

A first glance at this class does not immediately reveal where the console commands come from. We need to dig a little deeper aka start guessing and poking around wildly. To be able to run a command, the console input needs to be evaluated, thats for sure. So lets see if we can find where the input is read. In the OSGi console constructure, a new anonymous ConsoleSession is created. The ConsoleSession has a method called getInput() that returns an input stream. Let’s see who calls this method: place the cursor on the method name and press Ctrl-Alt-H to open the call hierarchy.

The first&direct caller, FrameworkConsole, seems not overly interesting in terms of command definitions. Let’s see what the next one, ConsoleManger looks like. A little hidden, somewhere in the middle we find a field of the type FrameworkCommandProvider. Now we’re pretty close to what we want to know. This is the place were – at least some – console commands are defined. The constructor’s comment pretty much tells us what to do:

So we need to implement a CommandProvider and register it with the service registry. For each command we want to implement, we need to have a method called “_<command name>”. We’ll implement only one command that calls our test runner. Additionally, I think we should implement the the getHelp() method to describe our command to the user.

It may be useful for your analysis to make changes to eclipse plug-ins to see how they behave. There is a simple recipe how you can do this without the risk of doing much harm: Import the respective plug-in from the target platform to the workspace, then create a launch configuration containing the workspace instead of the target platform bundle. You can now edit the standard eclipse bundle to gain a deeper understanding. When you are done, simply delete the bundle from the workspace (and from the disk as well).

Create a new class using the new class wizard, have it implement CommandProvider and generate the inherited methods.

Implement the getHelp() method so the output looks similar to the other commands. Have a look at the FrameworkCommandProvider for reference. Note that you can use Alt-Left/Alt-Right to navigate in the edit/browse location history. Useful as you can easily switch back and forth between your class and the reference class without using your mouse.

We call our command “check”, so we also need to implement “check(CommandInterpreter intp)”. The command interpreter is used to output the results from our tests. Take a look at the “*” methods in FrameworkCommandProvider for examples.

The complete class looks like this¹²:

Now we need to register/de-register our command provider in the Activators start() resp. stop methods:

• start our bundle as eclipse application, open the console view and test our command
• create a minimal run configuration and start the framework with the console and test there
• build the bundle and install it into the running framework (the running eclipse instance)
• or even install the bundle directly from it’s files in the workspace

Then we can use the console to install the bundle from the workspace. First, check that our command is not yet available by calling our  ”check” command. Our command is not found, so the help contents are displayed. Note that our command’s help text is missing as well. Then we can install the bundle if we know the project’s path on the harddrive.

-

We have now  installed a bundle that we are currently developing into our running eclipse instance. Isn’t that awesome? Of course you need to be careful with this approach as you can pretty much screw things up when fiddling with the hot bundle configuration of your IDE, but I think this approach actually makes sense when you are integrating with the IDE rather than building a standalone application.

What I mean by “strange loop” is — here goes a first stab, anyway — not a physical circuit but an abstract loop in which, in the series of stages that constitute the cycling-around, there is a shift from one level of abstraction (or structure) to another, which feels like an upwards movement in a hierarchy, and yet somehow the successive “upward” shifts turn out to give rise to a closed cycle. That is, despite one’s sense of departing ever further from one’s origin, one winds up, to one’s shock, exactly where one had started out. In short, a strange loop is a paradoxical level-crossing feedback loop. – Douglas R. Hofstadter

I’d be happy to see more custom OSGi console commands in the wild. As I said in the teaser, I still think this concept is underused. Also remember that the OSGi console can be configured to be accessible remotely using telnet. Now don’t tell me you can’t think of use cases for that.

I’ll push the complete sources of the example to github during the next days. In the meantime: Let me know if you get stuck.

I hope you enjoyed reading and that I gave you one or the other idea that may help you in future projects. Thanks for reading.

Contents

1. Prerequisites
2. Introducing Extension Points
3. The Restlet Registry - Extension Points
4. The Restlet Registry - Implementation
5. They tried to make me go to recap ...

The extension point is a piece of XML schema that defines how contributions to that point are to be structured, i.e. which attributes they need in which cardinality and of which type. The contribution to the extension point is made in the plugin.xml file of the contributing bundle. In addition to that, there needs to be some code that evaluates all contributions to the extension point and provides them to the core implementation. Note that this also separates the implementation of single components (code) from their use (contribution). In my experience, this leads to a significantly improved overall design as the definition modular structure of an application is clearly separated from its implementation and people tend to think about modularization earlier and more clearly as a part of the development workflow³.

Eclipse and others uses this paradigm e.g. to provide IDEs in very different flavors^{4 5 6}, but they all share a common core.  I daresay that this  is one of the key factors to the success of Eclipse and its wonderfully vibrant and diverse ecosystem. The implementation of extension mechanism is provided by the Eclipse Equinox project ⁷. You could argue that a similar result can be achieved by using plain OSGi (declarative) services, perhaps we’ll do so in a later post. For a comparison refer to Neil Bartlett’s excellent posts^{8 9}.

• Resources
• Components
• Applications
• Routers
• Filters

To avoid clutter¹⁶, we’ll put all registry components into a new bundle. Create a new bundle as described in the first post ¹⁷ and call it “net.wolfgangwerner.restlet.registry”. 

Let’s start with the first extension point, Resources. A resource consist of an ID and a corresponding implementation class. First, activate the editors for extensions in the new project’s properties.

To be able to reference the the ServerResource interface, it needs to be added to the registry bundle’s dependencies.


After that, open the MANIFEST.MF file from the META-INF folder an go to the extension point tab. Click “Add” to add a new extension point. Enter ‘resources’ as ID ¹⁸ and ‘Restlet Resources’ as name.

Clicking “Ok” takes us the extension point schema editor. You should really enter useful information on how the extensions contributed will be handled. The function of your extension point may seem clear to you now, but remember you are building an interface for public (more or less) consumption.

Now let’s go to the “Definition” tab and add a new element “resource“. Add the attributes “id“, “name” and “class” to the new element. IDs  and names should have the type String; Classes the type Java with the restriction that contributed classes must implement Restlet’s ServerResource interface. Then select the ‘extension’ element and add a “New Sequence” of the cardinality 1:n. Add a reference to the “resource” element to the new sequence.

The next extension point to implement  is the one for Restlet Components. It should be able to handle a collection of component elements, each with a name for human (developer) readable representation, a list of servers it uses (each with protocol and port) and a list of referenced resources. Note that if you create references to IDs, you can also restrict the element you want to reference. Go ahead and try to create the extension point on your own now. If you get stuck, the screenshots¹⁹ below should help.

• Resources
  • resource (1:*)
    • id (String)
    • name (String)
    • class (Java, implements org.restlet.resource.ServerResource)
• Components
  • component (1:*)
    • name (String)
  • a  list (1:*) of elements of the types
    • server
      • name (String)
      • protocol (String)
      • port (String)
    • resourceReference  (1:*)
      • urlTemplate (String)
      • resourceId (Identifier, Restlet Resources/@id)

Go back to the original net.wolfgangwerner.tutorial1.restlet bundle and open the plugin.xml file and go to the “Extensions” tab. Click “Add” to add a new extension point to contribute to. In the following dialog, deselect “Show only extension points from the required plug-ins”. Select the resources extension point we just created and click “Finish”. When prompted, confirm you want to add the registry plug-in to the list of required bundles.

Since we specified a lower bound of one element for the resource element, one has already been created for us. PDE is smart enough to parse our extension point schema and configure the editor correspondingly. ²⁰

Enter an ID, a name and the implementing class. The ID is used later to attach the resource to the Restlet Component. You should use a fully qualified ID (i.e. including the bundle name) here to make it unique within the runtime²¹. Though you can choose any ID you like, using a fully qualified one protects you from name clashes with extensions in other bundles. The name will be used as label in the extension editor; use a label that helps you identifying it once you contributed a larger number of resources. To chose the implementing class, you can use the code assist shortcut Ctrl+Space.

Repeat the last steps to contribute the Greeting List Resource in the same manner.

Then add a component extension and use its context menu to define two servers (e.g. HTTP on port 80 and on port 8080). Then add a resource reference element, enter “/greet” as URL template and browse for the corresponding identifier²².

As we need to reference the registry bundle to get its extension points, we add an ID to its Activator. The ID is the same as the bundle id of the registry bundle²³.

To keep the code that evaluates the contributed extensions separate from our bundle life cycle code, we create a new class called RestletRegistry that encapsulates . We can simply ask the Platform to give us all contributions to a specific extension point.  We specify the extension point by its namespace ²⁴ and the name of the extension point. We iterate over the list of contributions and save the contents in our Restlet Registry. This is straight forward for the ‘id’ attribute but requires some thought for the resource class. While there is a shortcut to create an executable extension (read: Object) from a class attribute, this doesn’t help us: The Restlet API requires us to attach the resource’s Class. In a non-OSGi environment, we could simply call Class.forName(String), but this will fail here as each bundle has a separate class loader. Instead, we need to get the contributing bundle and let it load the class for us using its own class loaded²⁵.

Getting the data from the component extensions is pretty straightforward. We get the extensions as we did for the resources, create a Restlet component for each extension, then add the corresponding servers to it and attach the resources at the given URL templates.
To keep our code clean²⁶, we split the parsing into several small methods²⁷.

You’ll have noted that there are several exceptions that can be thrown when working with extensions. In real life, you’ll need to safeguard your code against invalid extensions²⁸. Invalid extensions should be ignored and logged but may not impact other extensions contributed to the same extension point or obstruct the operation of the core.

In the last post, we started our server from the Activator of the first bundle. Since we are going to start all contributed components instead of hardcoding them, we can delete this Activator class and remove it from the Manifest.

Now all we have to do to make it run is to tie the registered component’s life cycle to the one of our registry bundle and adjust our launch configuration to include and auto-start the registry bundle.

In this post, we improved our application by allowing the contribution of additional resources from other bundles as well.

The application is not yet finished, I left some work for you²⁹. The next step is to create more extension points to allow the contribution of other Restlet subclasses (Filters, Applications and Routers) and finish the migration of the version from post #2.

Prior art includes the presentation of Shams and Norris on eclipsecon 2008³⁰. Originally I wanted to give the code they created a try, but was deterred by a strange license and download process. Others have noticed that as well ³¹.

I will wrap the final results of the Restlet Registry with all extension points into a project ready to use, stay tuned ³² if you are interested. I’d also be happy to discuss whether the current extension point setup matches real world requirements and how it could be improved. Implementing a Restlet OSGi service is also very conceivable. Let me know if you want to help or simply go ahead and fork the repository.

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.

• greet: issues the currently active greeting
• manage: base for the administrative section
• manage/list: show all greetings
• manage/list/{mnemonic}: Display a greeting with GET, add or modify a greeting with POST, remove it with DELETE

Of course you can also DELETE  greetings:

Must. Resist. Urge …

… to throw in mostly unrelated OSGi stuff, but I can’t.

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.

Where to go from here

You now know how to assemble Restlet applications by using Components, Applications, Routers and Resources. You have learned how to enable and use the equinox OSGi management console. From the last post, you already saw how all this can be wrapped up into a standalone application.

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.