I wanted to share something I learned today about JUnit. Some of you may know this, but it was news to me.

My triggering problem was that I was writing some unit-tests which required OSGi to be started up. All my other tests were plain (i.e. non-OSGi) tests. Since I didn’t want to suffer from the startup delay every time I ran the unit tests, I thought about “ignoring” these OSGi dependent tests based on whether I was running plain tests or PDE tests. A bit of googling turned up an interesting feature of JUnit (since 4.4): Assumptions. Assumptions are defined in the Assume class and are basically the exact opposite of JUnit assertions: If an assumption fails, the test automatically passes. This keeps tests from failing when certain preconditions have not been met. Ideally these would be marked as “ignored” or “skipped” but still better than nothing (maybe someone with commit rights to the TestRunner could make this happen).

This neat feature allows us to do the following:

  @Before
  public void setUp() {
    Assume.assumeTrue( Activator.isOsgiRunning() );
  }

Now the tests will only be executed if they are running in an OSGi environment.

If you put this in an abstract base class that all PDE Tests inherit, these will be ignored when running in “plain” mode, for even quicker test runs. In that case be sure to name your @Before method in a unique way so it does not get overridden (and thus nullified) by subclasses.

These assumptions might also be useful for tests known to fail on particular platforms, JREs, runtime environments etc. Another neat addition to my toolbox. The bit of hair in this soup is that JUnit 4 support in Eclipse is a bit lacking, especially when it comes to the PDE build. Some of this is detailed in Bug #153429 which hopefully will be fixed in 3.6. (Hint: Vote!)

Tags: assume, assumptions, junit, pde build, pde test, preconditions, syndicate

Today I want to talk about one of the younger members in the Eclipse family: Jetty. It is great to have such an interesting project on board and it is yet another example of how Eclipse has become more than just an IDE.

What I wanted to with jetty was to create an executable, standalone and self-contained WAR. I first encountered this concept in Hudson. The hudson.war contains an embedded Winstone servlet container, which makes it possible to run the application by executing

java -jar hudson.war

This makes test driving the application really simple. The idea was to do the same with Jetty. Embedding the Jetty runtime in the war proved to be the easy part, as it was just a matter of declaring the jetty dependencies in the maven pom.xml.

The tricky part was telling jetty where to find the war-file to serve. My first try was to hardcode the filename, but that left a foul aftertaste. Finding a solution took quite some time, which is why I am posting this for future reference. This is the Main-Class used to bootstrap Jetty (adapted from the Wicket quickstart archetype):

import org.mortbay.jetty.Connector;
import org.mortbay.jetty.Server;
import org.mortbay.jetty.bio.SocketConnector;
import org.mortbay.jetty.webapp.WebAppContext;
 
public class Start {
 
  public static void main(String[] args) throws Exception {
    Server server = new Server();
    SocketConnector connector = new SocketConnector();
 
    // Set some timeout options to make debugging easier.
    connector.setMaxIdleTime(1000 * 60 * 60);
    connector.setSoLingerTime(-1);
    connector.setPort(8080);
    server.setConnectors(new Connector[] { connector });
 
    WebAppContext context = new WebAppContext();
    context.setServer(server);
    context.setContextPath("/");
 
    ProtectionDomain protectionDomain = Start.class.getProtectionDomain();
    URL location = protectionDomain.getCodeSource().getLocation();
    context.setWar(location.toExternalForm());
 
    server.addHandler(context);
    try {
      server.start();
      System.in.read();
      server.stop();
      server.join();
    } catch (Exception e) {
      e.printStackTrace();
      System.exit(100);
    }
  }
}

The interesting bit is the getProtectionDomain()/getCodeSource() part, which tells us the location of the war-file. That’s all there is to it. Presto, executable web-application powered by Jetty in jar.

Edit: Added the import statements as per Tim’s suggestion.

Tags: embedded, executable, hudson, jetty, servlet container, syndicate, war

In a previous post, I mentioned that an OSGi and Equinox book is in the works. Well, we are nearing completion of the entire thing. Since we started doing the book there have been many changes in direction, content and now the title.

The new title, “OSGi and Equinox: Creating Highly Modular Java Systems” is a much better reflection of the content and intended audience. Originally we were very Eclipse-focused.  How does Eclipse use OSGi, how does Equinox work, … As we wrote more and more of the code and the text it, of course, became clear that all of this stuff is generically relevant and applicable.

As a result, the book is now essentially a generic OSGi book that covers a wide range of standard OSGi concepts and details. Mixed throughout are specifics that relate to Equinox (yes, we talk about the extension registry). The net result, we think, is a technically sound, pragmatic treatment of OSGi with value add for people using Equinox.

Along with this rethink came a look at some new content that is not so generic but still hugely relevant. For example we added:

• More detail on provisioning with p2,
• Coverage of server side OSGi creating WARs that use the servlet bridge
• Distributed OSGi (RFC119) and ECF
• Great depth on Declarative services
• Many best practice and experience tips
• Even integrating Google Earth as a service!

Needless to say, we are pumped about this content and about finally getting the damn thing out.

Its not quite done yet but very close. The Rough Cuts content should be updated by early October and the final version in a book store near you by Christmas.

P.S. Yes, the 2nd Edition of the RCP book is still coming and hopefully is on a similar timeline. Type type type…

Tags: equinox, OSGi, syndicate

Yesterday I discussed some of the issues with XML. Today I’ll be taking a look at three of the potential alternatives that may improve on the current situation.

YAML

YAML Ain’t Markup Language. To quote the spec, it is a “human-friendly, cross language, Unicode based data serialization language”. While mainly designed with so-called agile languages in mind, it can also be used with more traditional languages. The format is more data-centric than document-driven. Even so, one of its primary design goals is good readability. It was heavily influenced by RFC 2822 (Internet Message Format). That means it looks a lot like mail headers. It features built-in support for lists, hashes (i.e. dictionaries or associative array), and common data types. It also allows elements to have multiple parents, which also allows cross-references. There are some more minor features that make working with the format easier. Here’s a small example of a YAML document lifted from the spec:

invoice: 34843
date   : 2001-01-23
bill-to: &id001
    given  : Chris
    family : Dumars
    address:
        lines: |
            458 Walkman Dr.
            Suite #292
        city    : Royal Oak
        state   : MI
        postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
    - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments:
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.

While YAML seems like a solid solution with implementations written for many languages, there are some issues, like the surprising lack of momentum in the software development community and the controversial use of significant whitespace.

JSON

The JavaScript Object Notation is basically a subset of JavaScript used to statically describe data. With the release of YAML 1.2 it is also a subset of YAML, which means every JSON document is a YAML file. Its focus is primarily simplicity and readability. While it is trivial to parse JSON in a JavaScript environment, its simplicity makes it also quite easy parse in other languages. Parsers for most popular modern development platforms exist. Being so easily accessible in browsers has earned it quite some support and momentum in modern web development, already often completely replacing XML in the AJAX stack. Here’s a small snippet lifted from the JSON Wikipedia page:

{
     "firstName": "John",
     "lastName": "Smith",
     "address": {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": 10021
     },
     "phoneNumbers": {
         "home": "212 555-1234",
         "fax": "646 555-4567"
     }
}

JSON is currently quite popular, though it may in certain cases be hampered by its simpleness. Maybe YAML forward compatibility can provide an convenient upgrade path, should a more sophisiticated format be necessary.

Groovy

Most of you may know Groovy as a JVM scripting language. I have also already blogged about using Groovy to replace especially painful parts of XML.

Groovy features a MarkupBuilder that let’s you create what is basically an XML DOM tree in memory using a slightly more fluent syntax. Have a look:

  car(name:'HSV Maloo', make:'Holden', year:2006) {
    country('Australia')
    record(type:'speed', 'Production Pickup Truck with speed of 271kph')
  }

Some might consider this just syntactic sugar but it really goes a long way.

But I think Groovy can also be used as a first class configuration language. There are already several projects out there that use groovy scripts for tasks that have traditionally been in the firm grip of XML. One such example is gant, which is basically just a thin wrapper to write ant files. Of course nowadays, everyone is using maven instead, but there’s also a neat tool for that: Gradle is build system configured using a Groovy DSL, while employing Apache ivy and maven under the hood. Take a look at this example from the official gradle documentation:

usePlugin 'java'
 
sourceCompatibility = 1.5
version = '1.0'
manifest.mainAttributes(
    'Implementation-Title': 'Gradle Quickstart',
    'Implementation-Version': version
)
 
repositories {
    mavenCentral()
}
 
dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}
 
test {
    options.systemProperties['property'] = 'value'
}
 
uploadArchives {
    repositories {
       flatDir(dirs: file('repos'))
    }
}

A lot easier on the eyes, while still providing interoperability with “legacy” systems like maven.

The power and expressiveness of groovy make it really easy to create domain-specific languages like these. Such a special purpose language might not always be desirable, especially when interoperability is a key concern. But for certain applications these DSLs might be a better solution than any general purpose format.

On the whole, these are interesting times we live in and I’m curious to see what the future holds in store. As I said before, XML is probably gonna be here for quite a while, but there are some compelling alternatives out there. What are your thoughts on the legacy of XML?

Tags: gant, gradle, groovy, json, syndicate, xml, yaml

There is a user interface design issue that has been bugging me for quite some time, but I haven’t been able to put my finger on it until recently. How do you best represent disabled interaction elements (most often in the form of grayed out buttons and menu entries)? The visual cue here is that the action is not available at the moment. While that information is quite convenient, it raises the obvious question of:

Why is that action not available?

Often the answer might be obvious to the experienced user but this isn’t good for novices.

What about new or inexperienced users? Can’t we ease the learning curve a little and help users get to grips with the desired functionality? This might help avoid statements like…

“Oh wow, so that’s what that button does. I never used it because it was always disabled.”

In many cases there might only be a single reason why the action is unavailable. That means if the button is gray it is fairly simple to figure out what is amiss. But in non-trivial applications there may be a whole host of reasons why an action can not be performed. Typical reasons include:

• technical reasons: e.g. a “delete” action can not be performed if nothing is selected
• infrastructure reasons: e.g. a required service is unavailable
• operational reasons: e.g. user has insufficient privileges, or  the action can only be performed during business hours
• business domain reasons: e.g. certain preconditions have not been met, or the action is incompatible with another action that has already been performed

That last reason can really be a big can of worms… because at least in my experience “businessy” applications have a propensity for growing complex rule sets that have to be modeled in software. That may even leave domain experts guessing why the button “re-evaluate taco consumption rates” is grayed out.

So is there way to deal with that problem in a more sophisticated and helpful manner?

Here is an idea how the information could be presented in a natural and obvious way.

Tooltip for disabled elements - Answering the question

We’re doing nothing mind-boggling here but it gets the message across. On the implementation side of things, I could imagine something analogous to JFace style validators to attach to the button so that the appropriate message can be created on the fly. This might make for a cleaner technical design because different concerns of when to disable the button can be decoupled. One big drawback of this approach is that disabled (Windows) buttons don’t seem to show their tool tips. It may be possible to work around this problem with some SWT-fu though.

A more radical approach to the whole dilemma is the standpoint that disabled user interface elements are design smells that should be avoided completely. Applications should be designed in a way to support the necessary work flows and guide the user along logical steps… instead of doing trial and error and guesswork.

After all, trial and error and guesswork should be a domain reserved for point-and-click adventures.

So have you run into this issue as well? What were your experiences or solutions?

Tags: button, disabled, swt, syndicate, tooltip, ui

During my last project I had the dubious joy to work with a boatload of command framework expressions (activeWhen, enabledWhen). I appreciate the need for such a framework… don’t go through the overhead of loading all the classes for dozens of plugins to determine which commands are available… and instead use a lightweight alternative inside the plugin.xml file. This neatly sidesteps all the osgi class loading runtime overhead, making the eclipse experience fast and snappy. And I have to admit I am a sucker for speed. So I am on board with the concept but how things work in practice aren’t optimal in my opinion.

I’m not a big fan of XML in general and the idea of writing code in XML gives me the shivers. I have written enough XSLT to know pain… in copious amounts. We already have a long-established notation for formal expressions: programming languages. There is a very good reason Java’s syntax (or that of any other popular programming language) looks nothing like XML.

One argument that proponents of XML often make is that you usually shouldn’t have to look at XML at all. Well, I think they are wrong. The XML leaks through the cracks way too often. As a developer I am probably more exposed to that than the average user but nevertheless I still have to put up with it. Sometimes there may be a layer of GUI eye candy in between, but for something as specific as an expression editor… the standard extension editor just doesn’t cut it for me.

With a quick look at the following image: Tell me when the expression is true. Oh right, you can’t – the expression is distributed over several tree nodes.

Classic expressions

Now let’s look at the XML. Only slightly better, but at least you can see everything at once. Still clocking in at 6 elements, the signal to noise ratio is abysmally low.

<handler
	class="groovy.expressions.handlers.SampleClassicHandler"
	commandId="groovy.expressions.commands.sampleCommand">
 <enabledWhen>
	<or>
	   <with variable="activePartId">
		  <not>
			  <equals value="groovy.expressions.navigationView" />
		  </not>
	   </with>
	   <with variable="selection">
		  <count value="2" />
	   </with>
	</or>
 </enabledWhen>
</handler>

To put my money code where my mouth is… so I tried to implement a more elegant solution to the problem. Note though that this is just a proof of concept hacked together in my spare time. I wanted to integrate a scripting language with the command framework so that expressions could be written as small snippets of code. The ecosystem of scripting languages is quite prolific at the moment, so there is a lot of choice. But choice is good right? I settled for Groovy since I had done some embedding experiments with it before. But I am convinced that other scripting languages would work just as well.

Hooking up the groovy runtime was a snap, adding another expression type (creatively named “groovy”) was easy as well. I found out before long that I had to specify which command variables to use. The first reason for that was that I had to bind these command variables to groovy variables – although this could also have been achieved with some propertyMissing trickery. The more compelling reason was that the command framework had to known when to re-evaluate the expression, i.e. when relevant variables had changed. The resulting expression now looks like this:

<handler
	class="groovy.expressions.handlers.SampleGroovyHandler"
	commandId="groovy.expressions.commands.sampleCommandGroovy">
 <enabledWhen>
	<groovy using="selection,activePartId">
	activePartId != "groovy.expressions.navigationView" || selection.size() == 2
	</groovy>
 </enabledWhen>
</handler>

Quite a bit more readable, eh? Notice the “using” attribute specifying the used variables mentioned above. It might even be possible to compute these variables by traversing the syntax tree of the expression. This feature is offered by some scripting engines and would mean we could completely drop the “using” attribute. The rest is just plain groovy code, and I’m sure most of you will have no problem understanding an expression like that.

Next I want to discuss some of the caveats and advantages of this approach.

Caveats:

Needs a scripting engine
As far as I know, Java 1.6 ships with a Rhino interpreter so that could be an option for the future. Other small scripting engines (e.g. BeanShell) could be integrated as well. That is unless the big bad licensing monster rears its ugly head.

Might need standardization
As mentioned above there is a whole plethora of scripting languages available right now on the JVM, so choosing “the one” might be a problem. Another option of course would be to delegate to JSR 223 and let the user decide.

Yet another language?
There might some developer resistance concerning yet another language to learn. While this is certainly a concern, some scripting options are very close Java (Groovy and particularly BeanShell come to mind). I would argue that the current XML expression language is “yet another language” to learn as well – and a cumbersome and ill-specified one at that.

Advantages:

Legible expressions
As mentioned above, the expression is much easier to parse for developers. The machine doesn’t care either way, but software should not only be list of machine-operable instructions but also as a means of documentation and communication. The current implementation falls way short in that regard.

Debuggable
Ever tried to debug a highly nested XML expression? Not fun, let me tell you. With “scripted” expressions in the worst case you can pepper your code with println statements. In the best case you can set breakpoints on your expression code editor. The latter would probably be quite a bit of work but I don’t think it is totally infeasible.

More powerful
I haven’t looked into it too deeply but the current expression engine is probably a turing tarpit eager for prey. A “proper” scripting language would gives us a well understood, turing-complete way to describe complex expressions. It would also make it easier to factor common functionality into shared functions in order to reduce coupling and repetition.

Improved Testability
A scripting environment might also make it easier to write and execute unit tests on the expression to verify its correctness. While this also possible with the current expression engine, it is quite a bit of work to get up and running. With scripted expressions one could fairly easily set up the variables and run a minimal execution wrapper around the expression code to test its behaviour in a classical JUnit test.

I put up the code on the github here. Basically the application is your vanilla RCP Mail example. The meat of the code is in org.eclipse.core.internal.expressions.GroovyExpression. Apart from the mucking in the expression engine, the only thing I did was add two commands and handlers with the same activeWhen semantics, but once described as classic XML and once expressed as Groovy code. Have a look, I’m looking forward to your comments and critique.

Tags: command, expression, groovy, scripting, syndicate

I’ve been pensive as of late since we shipped the Eclipse Galileo release. One of the things I personally have been thinking about is how we can improve our documentation process. Currently, the Eclipse platform team has its documentation in Eclipse Help format (mostly HTML)… all this is kept in source control. In its current shape, the documentation isn’t conducive for people to contribute. There’s a lot of hoops a potential contributor needs to jump through in order to contribute documentation. Even more hoops if our documentation contributor isn’t really a developer. I also know a few committers who dread doing documentation because they have to hack away at HTML documents.

Can we do better? I think we can.

I’m interested in crowdsourcing the documentation at Eclipse.

What do I mean here? Well, I luckily have one example in the Eclipse ecosystem that is crowdsourcing its documentation already. The Mylyn project has its User Guide on the wiki.

The Mylyn project then uses WikiText to parse this wiki markup via a script and generate relevant Eclipse help artifacts.

In the end, there’s one source for the documentation (the wiki) where a multitude of people can easily contribute to. If we look at the Mylyn User Guide, we can see there was a decent amount of edits involving people who weren’t committers.

I’ve been experimenting with this documentation process for PDE and am pretty happy with it. There were only a couple of roadblocks I hit, but that was mostly around making it easier to use some of the WikiText ant tasks within Eclipse. I also experimented with some html2wiki transformers to help convert some of the existing PDE documentation.

One of the reasons I was inspired to look at crowdsourcing documentation for PDE was an excellent series of articles by Ekkehard Gentz on PDE’s new target platform provisioning story. I thought to myself, how could get Ekke to easily contribute that documentation (or even future docs) to PDE where it could be beneficial to everyone?

One point to bring up is that a lot of the Eclipse documentation is on the Eclipse wiki (Eclipsepedia) already. The Eclipse user community has most likely come across Eclipsepedia already. We can also assume that most people are comfortable with wiki syntax or at least the editor that comes with MediaWiki by default. If this isn’t the case, we can try to install something like the FCKEditor extension for MediaWiki to make it easier.

Another point to bring up is that having the documentation sourced from the wiki may have an interesting benefit due to early adopters. For a real world example, I’ll talk about the Equinox p2 project. There have been some complaints that the p2 documentation wasn’t robust enough for early adopters. Well, what happens if those early adopters would be willing to be part of the documentation process? As users adopt the technology, they can document their experiences along with the p2 committer team. If this was set as an expectation, I don’t think people mind sharing their experiences and being part of a team trying to build a cool technology.

What do people think? Is this good for other Eclipse projects?

Would you be enticed more to contribute to official project documentation if it was easier?

Tags: documentation, eclipse, syndicate, wikitext