• (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.