Daddy, are we there yet?

On any project it's immensely satisfying to reach a well-defined milestone. And so it was with the RHEVM-API project, when my colleague Mark McLoughlin and I got our first milestone out the door yesterday.

So where are we at with this?

Well, 0.9-milestone1 is intended as a way-point to show how the official RESTful API for RHEV-M is evolving. Hopefully it'll motivate a few interested folks who've been sitting on the sidelines to grab a download, explode the tarball and have a quick play with what we've done so far. Maybe even ping us with some feedback on the list. So if you are a RHEV-M user with an eye to the future, here's your chance to get in at the basement and have some real influence on the shape of RESTful interaction with the Red Hat Cloud infrastructure.

For most folks, the API docco will probably be the first port of call (see under docs in the distro, no surprises there). The API reference is a quick read that'll give you a holistic picture of how the API is shaping up. The RESTifarians will immediately note that we've taken a moderately "high REST" approach, nice and HATEOAS-y :)

But if you'd like to get your hands a little dirty, the next step is grab one of our webapps and fire it up in your favorite servlet container (Apache Tomcat, JBoss, whatever takes your fancy). We use RESTEasy as our server-side JAX-RS infrastructure and tie it all together with Spring. We've provided two .war flavors, one that integrates with the RHEV-M PowerShell API (and thus must be run on Windows), and another giving a mocked-up implementation that can be run anywhere and offers a good feel for how the interactions are structured.

On the client side, the best way to get started is to use our interactive CLI shell. Just take a peek at the README under rhevm-admin, then launch bin/rhevm-admin{.bat} and take it from there. The supported commands are are fairly self-evidently named, vms:add, storagedomains:list, networks:remove and the likes, and all provide brief man-page style docco via a useful --help option. Anyone who has previously used the Apache Felix Karaf shell will get a strong sense of déjà vu from the command recall, tab-completion etc. And in the engine room, there's the rock-solid CXF JAX-RS implementation.

So go on, download it and knock yourself out!

Indentation Wars

Ever suffer from tab rage? You know, you're fixing or refactoring someone else's code, and the logic is solid but the indentation is all over the place. So much so, that your appreciation of what the code does is over-shadowed by how bad its looks.

At the recent project kick-off, we had occasion to debate what coding conventions should be put in place. A few general principles occured to me, crystalized in the following rules:

1. No endless debate.
   The first rule of code style is: you do not talk about code style.
   The second rule of code style is: you DO NOT talk about code style!
   Endless amounts of time can be burned splitting hairs over obscure rules like the requirement to signal abstractness with Abstract or Base in the class name. Believe me, I've been there. The trick is just to agree that once the rules are in place, they're treated as being eteched in stone. You don't have to like them, just follow them. Yep, I do have a slightly dictatorial streek.


2. Enforce the rules early and often.
   Do not rely on folks to follow the conventions out of community spirit. Neither is it a good idea to wait for code reviews to smoke out style issues. The rules must instead be enforced from the get-go. With an iron fist, I tells ya!
   Where IDEs such as Eclipse are used, ensure continuous builds flag style violations as you type them. Enable checking via checkstyle and/or PMD as part of all routine automated builds. Fail the build if any sytle violation is found, no ifs or buts. Make it so that resistance to the style police is futile.


3. Rules are made to bent.
   What, doesn't that contravene the preceding principles? Well yes it kinda does, but sometimes needs must. When a boatload of pre-existing code is being imported into a project for instance. Or when the style checker doesn't understand some new language feature, such as PMD's tendancy to trip over variadic arguments. In these cases, use //CHECKSTYLE:OFF comments or @SupressWarnings("PMD.theRuleName)" annotations to selectively exempt the least amout of code. Selectivity is the key here.
   


4. Skip checks altogether when appropriate.
   A tad contradictory again, but style checking does not come for free, and there is no point wasting time auditing code you already know to be clean. So when you build a fresh checkout for the first time, or when running the same test from maven multiple times without any code changes, the checkstyle.skip and pmd.skip properties are your friend.
   

fewRemainingStrands.tearOut(); EasyMock.expectLastCall().andReturn(yourHair);

Don't get me wrong, EasyMock absolutely rocks for unit testing.

But I've just burned half an hour with frustration, misled by the most misleading error message I've seen in a long while.

What does the following say to you?

java.lang.IllegalStateException: missing behavior definition for the preceding method call: someMethod(interface someType)

Maybe that you forgot to set an expectation for someMethod(someType)? Yeah that's why I thought too. But that would be too straight-forward. Wouldn't involve the fun of the chase :) Simply setting the apparently missing expectation doesn't resolve the issue. To my deep frustration, just now.

What EasyMock is really trying to tell you here is that you've called IMocksControl.replay() in the wrong place. Too late in the day, to be specific. After you've used one of your mocks in anger.

Distributed OSGi 1.0 ... Thunderbirds are Go!

Almost a year ago now, myself and Sergey Beryozkin started out on the road to building the official reference implementation for what was then just plain ol' RFC 119, being cooked up by the Enterprise Expert Group at the OSGi.

After quickly putting together an initial proof-of-concept based on Apache CXF, we moved the code to a sub-project of CXF and continued its development from there.

Fellow RFC 119 author David Bosschaert later joined us in the implementation effort, and became a CXF committer in the process.

After much refining of the RFC along with the expert group, multiple trips to Montpellier to eat chèvre and argue over the fine detail of the spec, a serious case of concall-ear and lots of updating the implementation along the way to follow the moving goalposts, we've finally released version Distributed OSGi 1.0.

So enough of the back-slapping, where's the beef, says you.

Well you can get started kicking around the reference implementation by downloading one of the three distribution formats we provide for your convenience:

1. Multi-bundle distro: cxf-dosgi-ri-multibundle-distribution-1.0.tar.gz
   
   Contains the dOSGi implementation and all 3rd party dependencies as separate bundles within an archive. Along with config snippets for both Felix and Equinox, to allow you to easily pull in all the required bundles without having to go through the tedium of typing many install commands in the shell.
   


2. Single-bundle distro: cxf-dosgi-ri-singlebundle-distribution-1.0.jar
   
   Contains the dOSGi implementation and all 3rd party dependencies wrapped in a single OSGi bundle so as to allow direct installation in your favourite OSGi container in one fell swoop. As long as your favourite OSGi container happens to be either Felix 1.4.1 or Equinox 3.5M4+, for these are the OSGi runtimes that support the OSGi Service Registry Hooks on which dOSGi depends. That's the magic that allows us to intercept client calls into the OSGi Service Registry and do some sleight of hand to ensure there's a proxy transparently registered for the remote service.


3. Source distro: cxf-dosgi-ri-source-distribution-1.0.zip
   
   Contains the entire source tree for dOSGi, for your building pleasure. For those of you who prefer to get your hands dirty from the get-go :)
   

For any tar-phobic Windows users, there are .zip versions of the distros also available.

 
Docco-wise, the best starting point for getting your head around dOSGi is the Getting Started Guide.

There are a number of samples also to play with, illustrating various approaches to enable transparent remoting on your common-or-garden OSGi services. If you're new to the ideas behind dOSGi, you'll find that the detailed walk-through of the greeter sample should cause a few lightbulbs to flash.

Your feedback, we value. Even when its of the form "this, I don't understand" or "that, looks like its broke". So if you've got any, be sure to drop us a note on the CXF lists.