Eclipse and Asynchronous Unit Testing

I’ve been retro-fitting hundreds of JUnit tests to Archi‘s code base. It’s a Zen meditation, as the process of devising the unit tests ensures that I re-engage with the code, clean things up, refactor here and there, and finally understand what that nifty algorithm does that I wrote 3 years ago. Like children not eating their greens, no-one wants to write unit tests. But it’s a valuable thing to do and rewarding, especially when you see the green bar in Eclipse:

Testing

Perhaps the process of testing and being rewarded by the green bar is an example of “gamification”? Maybe, but I’m not interested in vacuous neologisms, I’d rather just get stuff done.

Some tests that I wrote were failing. The code that these tests was calling depended on events occurring in the UI of the application, such as an editor window opening. The tests were finishing before the editor window opened. Not sure what to do about this I went for a jog to have a think. And then I remembered that I already had the answer in one of my own posts, Xcode and Asynchronous Unit Testing. This has turned out to be quite a popular post in the Xcode and Objective-C community, solving a common problem. So I wondered if Eclipse would be happy with a similar pattern. I’m never sure what’s going to happen when I start playing with threads and dispatch queues.

Here’s my solution, an abstract Java class called “AsyncTestRunner”.

public abstract class AsyncTestRunner implements Runnable {

    boolean waiting = true;

    @Override
    public void run() {
        stop();
    }

    public void start() {
        Display.getCurrent().asyncExec(this);

        while(waiting) {
            if(!Display.getCurrent().readAndDispatch()) {
                Display.getCurrent().sleep();
            }
        }
    }

    public void stop() {
        waiting = false;
    }

}

This class implements Runnable which has one method, run(). This run() method will be called by the current Display instance asynchronously in this line:

Display.getCurrent().asyncExec(this);

Meanwhile the read and dispatch process will go off and do its thing in the event loop:

while(waiting) {
    if(!Display.getCurrent().readAndDispatch()) {
        Display.getCurrent().sleep();
    }
}

This ensures that UI tasks can be completed.

Here’s an example of how we use it:

AsyncTestRunner runner = new AsyncTestRunner() {
    @Override
    public void run() {
        super();

        // Run some code that needs testing in the UI
        Object someThing = ...;
        assertNotNull(someThing);
    }
};

runner.start();

Here, we create a new anonymous instance of AsyncTestRunner and implement run() with the testing code and then call its start() method. Be sure to call super() in the run method to invoke stop() which sets a boolean flag to false which breaks the event loop in the start() method.

The class may seem verbose with its stop() method, you could simply directly set the waiting flag to false, but I wrote it like this so it can be sub-classed and to make it obvious what’s going on. I also like the idea of a run() method consisting of one stop() method.

public void run() {
    stop();
}

Very Zen.

So far it works in both Eclipse 3.8.2 and Eclipse 4.4. I may find a gotcha further down the line, and I may refine the class in the future, but so far it’s looking good. If it can be improved I’d be glad to hear about it.

Do you love your users?

Alan Rusbridger, the editor of The Guardian newspaper, was recently asked by a UK home affairs committee investigating the Snowden leaks, “Do you love this country?” This is not a question I will answer, but I do find myself asking a similar question of software developers – “Do you love your users?” Or, put another way, “Why do you hate your users?”

As the developer of Archi, the free ArchiMate modelling tool, I’ve put in many hours of my time, and much soul-searching, trying to create an application that works simply and elegantly, hiding complexity from the user and, above all, not crashing. I’ve thought deeply about what users want and what they probably don’t want, and I’ve listened to, and responded to, user feedback. So my answer to the question, “Do you love your users?” is unequivocally, “Yes!”

I’d like to illustrate this with an example of the process of thinking about usability in my software, and finish with an example of “user hatred” in another piece of software.

Show me the love…

I just implemented a new feature in Archi – to let the user define the line colour of a selected object in a diagram. This wasn’t too difficult, I just followed the standard presentation in the Properties pane. But then it got a bit more complicated when I added an additional option to derive the selected object’s line colour from its fill colour. Again, this wasn’t too hard, but it did present a usability challenge – one option negates the other. If the latter option is selected in the application’s global preferences, then any user line colours are ignored. So how would this look in the object’s Properties pane?

Archi Properties pane
Why are they disabled?

The problem is that the line colour selector buttons are always disabled. Whatever you do, they remain disabled since the global preference is set to derive line colours from the object’s fill colour. So why on earth are the buttons there? Perhaps the user needs to do something special to the selected object to enable them? Search in the user manual? Perhaps phone the help-desk? As it stands, this is a perfect example of the software designer hating their users. It’s the equivalent of inviting someone to dinner and then hiding the food in the cupboard.

So let’s show some love and try and solve the problem. Let’s kindly explain to the user that if they want to set their own line colour, they should have not been so stupid to have set it in the application’s preferences in the first place:

Archi Properties pane - better
Hmm…why should I?

Well, why should the user have to do that? They can’t even remember where the preferences are, let alone which preference to look for. Out with the manual again!

Perhaps the better solution is to not only explain why the feature is disabled, but also to offer a link that will open the preferences dialog window and take the user to the preference that will solve the problem:

Archi Properties pane - much better
A bit better, but…

Clicking the link takes the user to the Preferences dialog window:

Archi Preferences dialog
Preferences dialog – set it here

This is not a perfect solution, since the user has to think about whether to disable or enable the option. However, it’s a lot better than before. But wait…

…why not just completely hide the colour buttons in the Properties pane when the feature is not available? This way you wouldn’t even need to show an explanatory text and link. Well, I thought about this and this creates a different problem – the user might never know that the line colour feature exists. By greying out the buttons I’m providing a hint to the user that the feature is available under some circumstances. The additional explanatory text and link then takes the user to the preferences dialog so that they can see for themselves how and why this is an option – coaching and coaxing the user.

Even this solution sucks. There are just too many buttons cluttering up the screen. Back to the drawing board.

This is better:

A better solution
A better solution

Here I’ve combined all buttons into one control – the colour selector, as before, and the “Default” and “Preferences” into a drop-down menu available from the right of the selector. I even re-used the control for the Font selector. Nice.

And now for something completely different…

That is a small example of the process I go through when demonstrating the love I have for Archi’s users. But what about software developers who seem to hate their users? I give you Protégé, an open source ontology editor from Stanford University. Here’s the opening screen on Windows:

Protege - WTF?
Protege – WTF?

This just broke Software Rule #1 – Don’t Throw Shit at the User.

Ok, how about simply opening a file in the current editor window? Here’s the result:

Protégé - oh dear...
Protégé – oh dear…

Protégé also has a menu item called “Refresh User Interface“. Really? You don’t get a dog and bark yourself. Come on, this is supposed to be Stanford Frickin’ University.

You know what? I think the Protégé developers hate their users.

I finally found the long lost bug in Archi

I finally traced and fixed a nagging bug in Archi that can lead to orphaned diagram elements or, put another way, a corrupt model file. This was an issue that had occurred for a small number of users for some time, but one I’d never been able to reproduce. Until three days ago.

Analysing an Archi user’s specimen file I discovered that some folders were being stored in XML as <element> tags and not as <folder> tags. This meant that some diagram view objects could not be matched to their corresponding model elements in the model tree. This in turn meant that it was possible to delete the referenced model element thus leading to an orphaned diagram node. It turned out to be a dumb logic bug in the model tree’s drag-drop handler. An edge case, but with serious enough consequences. You can view the bug for yourself in all of its glorious stupidity at Github.

Put simply – if you dragged and dropped a folder onto the same parent folder your file could get screwed.

Fixing this bug has been a cause for major celebration. So much so that, after releasing the new version of Archi, I broke open a bottle of Prosecco and immediately emailed those Archi users who had reported the problem with the good news. Tetelestai!

Now that this bug has finally been squashed and a new build published I hope that all Archi users will download the latest version from the new Archi website.

rip

Archi – an Open Source ArchiMate tool (part 4)

(Continued from Part 3)

Impact and Popularity

In this final blog post in the series, I want to examine the impact and popularity of the Archi tool.

Archi 2.4 was released in December 2012. In the previous two years of development I had implemented a fairly respectable feature set, and devised some unique features, thanks to a source of funding that paid my wages, and the feedback and enthusiasm of Archi’s users.

archi_viewpoint_total
Archi 2.4

Just how popular has Archi been? And how popular is Archi right now? I suspect that it has been, and still is, very popular.

In 2011, Christina Smart, from a Jisc-funded organisation, interviewed me for a blog post, Business Adopts Archi Modelling Tool, and I spoke of the possible reasons for the extensive adoption of Archi, especially in the business sector:

CS: Archi has a growing number of users outside education, who are they and how did they discover Archi?
PB:
…I am also aware of other commercial companies using [Archi], but how did they discover it? Well I think it’s been viral. A lot of businesses spend a lot of money advertising and pushing products, but the alternate strategy is “pull”, when customers come to you. Archi is of the pull variety, because there is a need out there, we haven’t had to do very much marketing, people seem to have found Archi on their own. Also the TOGAF (The Open Group Architecture Framework) developed by the Open Group is becoming very popular and I guess Archi is useful for people adopting TOGAF.

CS: Why do you think it is so popular with business users?
PB: I’m end-user driven, for me Archi is about the experience of the end users, ensuring that the experience is first class and that it “just works”. It’s popular with business users firstly because it’s free, secondly because it works on all platforms, thirdly because it’s aimed at those making their first steps with ArchiMate.

When I spoke about the concept of “pull”, I was referring to the book, The Power of Pull, by John Hagel. Tom Graves, the author, Enterprise Architect, “business anarchist”, and self-proclaimed “confusionist”, once said to me, in a telephone conversation, that he thought that Archi’s popularity was due, partly, to this “power of pull”. Archi had no advertising budget, it had no pushy salesmen, nor was it ever promoted in any significant way. Instead, users discovered it by word-of-mouth, by a friendly recommendation, or via a simple Google search. Together with an agile feedback loop between developer and users, popularity increased. Users clearly liked the whole package – both the developer and the product.

This is not rocket science. For me, this approach comes easily and naturally. I only have to think of the products and websites that I like, and think about why I like them, and just do the same. The key is to be open, clear and honest. People will come to you. I’m not a big fan of websites that claim to be selling a software product but where you have no idea what the software does, how to download it, how much it costs, or what it looks like. Instead you get a series of stuffy “white papers” explaining the benefits of nebulous “solutions” written in MBA sound-bites. Nor did I employ the “push and grab” approach – flooding the twitter-verse with tweets telling us of the “Top reasons to get a grip on the latest #archimate and #togaf trends!!!! Read our new white paper!” I know where “white paper” belongs in my household...

If you look at the front page of the Archi website it’s immediately clear what Archi is, does, how much it costs (nothing), what it looks like (screenshots), and where to download it:

Archi is a free, open source, cross-platform tool and editor to create ArchiMate models.

And I strongly believe that even the largest of organisations can relate to this honest, no-nonsense approach. That’s why I call myself a “code punk”. The software may only play three chords, but they’re honest and powerful ones.

Statistics and Google Analytics

I think we can get a sense of this popularity by looking at some statistics for that period. The old Archi website (no longer maintained), was tracked by Google Analytics. First off, let’s take a look at the figures for the year previous to when this blog post was written (September 21 2012 to September 21, 2013):

Site Visits
Archi Website Visits

Here we can see that in this yearly period, there were 71,752 visits to the website, of which 44,444 were unique visitors. Taking the unique visits alone, that’s about 3700 a month, or about 850 a week. Not bad. We can also see that a large proportion of visits (10,558) came from the Netherlands. This is not surprising given that ArchiMate is, as well as cheese and tulips, a Dutch product. The UK and the US follow closely behind. Here’s another view of the demographic location data:

Analytics Archi Location 20120921-20130921
Archi Website Locations

It’s interesting that India and Russia are in the top 10. Russia has a thriving community of Archi users, perhaps due to the fact that it was translated into Russian by Anatoly Levenchuk from Moscow. Again, this is an example of how the Archi community has contributed significantly toward its success.

Software Downloads

But what about the download numbers of the actual software?

Archi Downloads
Archi Downloads

Let’s take the figures for Archi version 2.4.0. Here we need to make some adjustments because Archi 2.4.0 was released in December 2012, and this reporting period starts from September 2012 (hence the figures for Archi 2.3.1). Therefore, this represents about 9 months for Archi 2.4.0. Adding up the numbers for the Windows executable (8,374), the Windows zip install (2,671), the Linux version (487), the Mac 64-bit version (360) and the Mac 32-bit version (67) we get a grand total of 11,959 downloads of Archi over a 9-month period. That’s about 1300 downloads a month.

It seems a lot. We could knock off a percentage for duplicate and failed downloads. But then again, these figures only show who actually clicked on a download link on the downloads page. There are probably direct downloads linked from other pages and referrals. Also, some organisations that I know of roll out only one centralised copy of the software throughout the company, so this might only show as one download, or not show at all if they have a direct link.

However you interpret these figures, I feel confident in thinking that Archi is probably the most popular ArchiMate modelling tool. Of course, this assumption is based on these download figures and the many emails I’ve received over the last three years. Put it this way, there are a couple of Fortune 500 companies that I know of, and some very large organisations that use Archi as their only ArchiMate modelling tool. I believe also that a couple of large training organisations use it as their training tool. Given that it was only meant to be a “starter” application, I find that interesting.

Archi has come a long way since its initial incarnation as a “proof of concept” tool.

Futures

Where now for Archi? I no longer work for the organisation that hosted the original development work on Archi and it’s time to move on! Also, Eclipse, the software framework on which Archi is built, has changed radically with the latest version 4, and this introduces some new challenges which need to be solved. The answer lies in the fact that the software is open source. All of the code can be found at GitHub, and is released with a MIT-type licence. If Archi is to be sustained, it will need to be migrated to Eclipse 4, and it needs to implement some of the most requested features from its hundreds of users. This will require the input of other developers, and so the next step is to get more developers on board.

I’d like to say thanks to all Archi’s users and supporters, for playing their part and allowing it to happen. It was, and is, I think, a success. With around 1000 2000 3000 downloads each month I’d say that Archi is quite popular.

Update 4 October 2013 – I’ve created a new and supported Archi website at https://www.archimatetool.com

Update 11 March 2014 -We are now seeing around 3000 downloads a month of the latest version of Archi at https://www.archimatetool.com. Since I set up this new website, Archi’s popularity and reputation has doubled and we’ve also attracted some additional developer interest.

Archi – an Open Source ArchiMate tool (part 3)

(Continued from Part 2)

Release early, release often

A very early version of Archi was ready by mid-March 2010. I demoed this to a roomful of enthusiastic delegates at an Enterprise Architecture Practitioner Group (EAPG) meeting in Birmingham, UK. It was warmly received. The features were very basic, but there was enough there to whet the appetite.

An alpha version of Archi, version 0.7.0, was released on April 8th 2010. Even though an alpha release, this version actually implemented most of the core functionality. All three ArchiMate layers were implemented, as was support for multiple Views and you could save the diagrams as image files. Further alpha and beta releases were made in April and May 2010. These versions focussed on fleshing out the feature set, bug fixing and getting early user feedback.

The official public version 1.0, was released on June 18th 2010 in time for the summer EAPG meeting. This version implemented the main feature set together with all the “hints” available in the Hints window, and Help documentation. Again, it was received well. We also had a website, a Google forum, and a small, but growing, Archi user group. The 6 months were up. (I should add, not to promote my ego, that this was all done by myself – there was and has only been one developer/documenter/website maintainer/helpdesk/designer/stunt coder.)

Beyond 6 months and Global uptake

It turned out that Archi was not just being used by the Jisc projects in UK higher education. Professional and student Enterprise Architects everywhere were downloading it. As a result of its early success, 6 months funding turned into 24 months funding, taking me up to December 2012. I have to extend enormous gratitude to Jisc for providing me with the funding to work on Archi for all of that time.

During that overall period I added many more features in response to user feedback posted to the Archi User Forum and received by email. This feedback resulted in Archi’s infamous “Magic Connector” and inspired many other features that contributed to its ease of use and popularity.

archi-sketch
Planning Archi

Feedback was generally positive. Ideas came flooding in from users around the world. News of Archi was spreading fast. Here are some examples of feedback from the first few months of its release (anonymised):

“…first impressions are that it’s a much nicer experience to actually model with… The feeling I get from Archi is that it’s helping me to create shapes, link and position them rather than jumping around dictating how I can work with it. And the models look much nicer too… I think Archi will allow people to investigate EA modelling cost free to see whether it works for them, something that’s not possible at the moment.” – Staffs University, UK.

“It’s a really impressive application and very nicely built on top of Eclipse.” – Healthcare Institute in the Netherlands.

“Archi – nice work – looks very promising – I hope you can find the time and money to keep building it out!” – EA consultant, Australia.

“I’m new to EA world, but Archi 1.1 makes me feel like at home! So easy to use and so exciting…” – Senior Engineer, Russia.

“The most interesting tool to date for Archimate is yours, also because it is based on Eclipse and GEF.” – PhD student from France adding extensions in the Telecom domain.

“Version 1.3 looks great!  We are rolling Archi out to all our architects next week.  The ones who have tried it so far all love it.” – Senior Architect, Insurance company, US.

“It’s a nice alternative… In my first attempts of using the tool I found it to be very useful and promising.” – IT Architect, Delft University of Technology.

I think it’s interesting to note the efficacy of a fast feedback loop between me, as the developer, and an enthusiastic group of users. As the musician Robert Fripp likes to say, it’s important to remain “small, mobile, and intelligent”. Without the constraints of formal processes and methodologies imposed by the parent organisation, I was able to develop the software iteratively and quickly, implementing new features that the users, and I, felt were important. Open beta testing allowed me to fine tune the features as the users suggested.

Archi allows for EA conversations

It was clear then, and still is now, that the availability of Archi as a free tool allowed for a greater degree of sharing and discussion of EA in the UK Higher Education sector, and, indeed in the wider community, both commercially and non-commercially. Archi was the core tool used at various Modelling Bashes at UK Universities, a London King’s College ArchiMate workshop, and many of the discussions in the EA Practice Group meetings revealed that practitioners were sharing models created using Archi.

As I attended more EA Practice Group meetings, overheard discussions, and saw increasing numbers of presentations using screen-shots of Archi models, I saw Archi’s presence growing more and more. Why was this?

That Archi is free and open source is one good reason. Another reason is that it runs on all three main platforms – Mac OS X, Windows, and Linux. But looking at the rich feature-set of some of the major modelling tools tools out there I wonder why anyone would choose Archi. Could it be the pricing model? The bigger tools are great if you’re a large company and can afford the licence, but not so great for the single user, the EA student, the small enterprise, the cash-strapped University.

Archi’s popularity puts a great pressure on me, as the only developer. Users want Archi to support some of the features that these other tools have. For free, of course. They would love to have model repository support, sharing of models, versioning of models, export to this format, import from that format, and so on. Of course, there’s always the get-out clause – “It’s Open Source. Perhaps you’d like to contribute…?”

But whatever the future for Archi, what has been clear to me is that in its existence it has provided very many people with a means to share models and EA conversations that might not otherwise have been possible.

(Go to Part 4)

Archi – an Open Source ArchiMate tool (part 2)

(Continued from Part 1)

Beginnings

As I wrote in Part 1, I had to get something out of the door within the given 6 months of project time funded for Archi. We had said, in the first planned stages, that the deliverable would be a “proof of concept” application, with the hope that we might get additional funding beyond the 6 months if there was enough interest in the project. I was never really interested in creating a “proof of concept” tool, I wanted to deliver a full-blown application, ready for real-world usage.

Some developers are, let’s say, a little unsure of themselves, inclined to conceal their code behind a veil of false modesty. I’m happy to say that I’ve never suffered from this affliction, as I like to get the first few lines of code out there as soon as possible. If it’s junk, I want to know. Maybe I’m naive, or overly enthusiastic, or maybe it’s because, as the character of Mister Wolf in the film Pulp Fiction says, “I solve problems”.

If I’m writing a desktop application, such as Archi, I like to start straight away by creating an empty application window with the App’s title in the top bar, an icon, a basic menu and an “About” dialog box declaring me as the author (to take the blame, not the credit). That’s it. This only takes a few hours to put together, but it means that you have an App. It doesn’t do anything except open, close and show the “About” box, but you have a freakin’ App. It’s like creating a frame for a picture, or an outline for a novel. On day 1 you can launch your App and you can show it to people. It’s a tangible thing. This is really important if you want to encourage interest in your endeavour, and convince people that you just might be able to do the impossible. Also, this is Open Source software funded by public money, so transparency is key.

After the initial code was written, I created a project at SourceForge and committed the code. It was a CVS repository then, now no longer visible since the transition to Git a year later.

Frameworks

Choosing a modelling and graphical framework was the next task. At the time, I could already hack something in Eclipse’s Graphical Eclipse Framework (GEF) which would take care of the boxes and lines, and I could use the Eclipse Modelling Framework (EMF) for the model, persistence, and model notifications. Additionally, there is the Graphical Modelling Framework (GMF) which combines the two frameworks but this turned out to generate too much Voodoo Code.

modelling wtf
The Eclipse Modelling World

Voodoo Code is a term I use for frameworks that generate code and artifacts based on a given set of user-provided meta-models and input by some mysterious and opaque process. Something very, very clever is going on in that Voodoo, but you sure as hell don’t know what it is. Many lines of code are automagically generated, but you don’t know how to modify them, or what might break if you do. I have to confess to being horribly confused by GMF, I feel scarily not in control; and of course there’s the old problem of the lack of documentation in the Eclipse eco-system (don’t get me started on that subject). And I only had 6 months to work with. It was like this Dilbert cartoon:

dilbert
Frameworks

I went with the “old school” option – a combination of EMF to create the model and persistence framework, and GEF to handle the drawing graphics, and I would hand code the “glue” between the two frameworks. The cross-platform, Java-based, Eclipse framework could handle all the windows, menus and other GUI requirements. At least this way I could understand and maintain the code without feeling that it was all sinking away from under my feet. I should say that the EMF does in fact generate code, but it’s boiler-plate code, easily modifiable and very easy to update (and EMF has great documentation and support). Eclipse did a great job with that framework. Not so sure about GMF, though. A colleague once remarked that he wished GMF could be “un-invented”.

I spent the next two months developing a basic EMF meta-model for the ArchiMate model and the Application model, and linking this to the GEF to draw the boxes and lines, and battling with the Eclipse framework in order to beat it all into some coherent shape. At one painful point in the development process I grew doubtful, abandoned EMF completely, and spent the next three days and nights coding an alternative. On the fourth day I realised that I had effectively re-written EMF, although in a half-baked manner. The following day, I put it all back again, and really appreciated how well EMF has been devised. I wasn’t using Git version control in the early development phase, I was using CVS. If I had been using Git, I could have created any number of alternative, experimental branches with ease.

Go to Part 3

Begin typing your search term above and press enter to search. Press ESC to cancel.