Hexagonal Architecture

Hexagonal Architecture isn’t new.  The idea has been about for a long time,  Alistair Cockburn talks about Ports and Adapters, however it hasn’t received widespread adoption.  Kevin Rutherford brought Hexagonal Architecture to my attention and I’ve been a little bit enamored with it since.

I won’t repeat poorly what others have already written well, read their work for a more in-depth description of Hexagonal Architecture.  Conceptually you can think of Hexagonal Architecture as two hexagons, one inside the other.

The inner hexagon contains Domain objects and has no references to the real world e.g. disk I/O, network, HTTP, XML or any other concept that is used to interface with the real world.

The outer hexagon contains Adapters that manage the interaction between the Domain objects and the real world.  They do not have responsibility for any Domain logic.

Everything outside the outer Hexagon is the real world.  In reality there would be other hexagonal systems arranged around the outer hexagon, hence why a shape that tessellates is important.

Hexagonal Architecture

If the Domain objects are not allowed to have any reference to the real world, and the Adapters are part of the real world, then you might ask how do the two work together?  The answer is that the Domain contains interfaces that represent what the Domain objects want to do.  The Adapters then implement these interfaces.

It is correct for the Adapters to depend on the Domain, but the Domain should not depend on the Adapters.  This gives you the power to replace a specific Adapter at any point without changing the Domain objects.  Say you want to change from saving something in an XML file to saving it in a database.  Just write a new Adapter that stores stuff in the database and plug it in place of the XML file Adapter.  The Domain doesn’t change because as far as it knows it’s just interacting with the ‘save this stuff for later’ interface.  How it goes about saving it is up to the Adapter objects.

We’ve been using Hexagonal Architecture on our project at work and I’ve noticed a few things.  Firstly it is possible to fit it into an existing code base.  We changed the entire code base to hexagonal and it didn’t take too much effort.   A bit of moving classes around into different package and removing a few dependencies that shouldn’t have been there in the first place – we even found one front end piece of JavaScript that was dependent on the back end data provision technology.  We were a little shocked to say the least!  So long as you have been encapsulating things appropriately it really isn’t too time consuming.

Secondly testing becomes much easier.  Duncan Nisbet has looked at hexagonal from the viewpoint of a tester in greater depth.  I’ve found the tests for the Domain objects become much easier as they’re all just pure Java.  There are no complex integration points to fake for the tests and because they don’t hit the real world in any way they run fast, really fast.

The Adapters become easier to test as well, because they are doing just the adaption between the Domain and the real world without having to include any Domain logic.  I’ve found that getting the adapters as thin as possible can be turned into a bit of a sport, unfortunately not one that might qualify for the Olympics.  Also the thinner they are, the faster the adapter tests run.

This is all good, but doesn’t explain why I’ve been enjoying Hexagonal Architecture as much as I have.  It took me a while to realise exactly what it is.  It takes your daily programming life back to that fun stage when you were learning a language.

Writing Domain objects involves a lot of tasks similar to those used when learning to program.  Such as: “Here is a list of objects, sort them and return the top three”.  You don’t know or care where the list came from.  Just that it’s here now and it needs sorting.  You don’t care where the result is going, only that it’s the top three from the list you were given.  The vulgarities of the real world don’t come and slow you down by having to open up the Java Network API or figure out how to read in an XML file and parse it’s contents.

The reverse is true of writing the Adapters.  Much like when you first realised you could open any socket you liked and flood the network with rubbish, writing Adapters allows you to not care about the business logic.  You can just hack about with the API you’re using until you have something working, smarten it up a bit and then you’re done.  The requirements of the Domain logic are not imposed upon you, only the interface the Domain objects want to use, which is typically a lesser restriction.

Much like Ruby puts the fun back into programing, I would suggest that Hexagonal Architecture puts the fun back into software architecture.

Posted in Software Development | Tagged , , | 3 Comments

Time Capsule Firmware Update Problems

The latest firmware update for my Time Capsule announced itself to me yesterday. I should have checked user forums to make sure it didn’t have any ill effects, but it was all too easy just to click the ‘Update Now’ button. The firmware installed itself ok and rebooted the Time Capsule, only it didn’t come up again. The wireless was non-existent and AirPort Utility couldn’t find the Time Capsule on the wired network although it was acting as switch without any problems. The light on the front was solid amber, not flashing.

After about twenty minutes I was convinced it wasn’t just being slow to come up. I attempted the generic electronic equipment solution – turn it off, then back on again. In the industry we call this ‘Power Cycling’. It didn’t work.

Next was the Time Capsule user guide. It says in this situation to reset to factory defaults by pressing and holding the tiny button the back of the Time Capsule with a ball point pen for five seconds. It took me a while to find the button as I use a cable lock with the locking slot. The lock obscures the reset button so you can’t reset it when it is locked – nice feature! Unlocking and pressing the button for five seconds didn’t have any effect. The light was still solid amber.

The next step in the user guide says to press and hold the reset button whilst power cycling the Time Capsule. I tried this and the Time Capsule came back online, but with the factory reset settings.

Luckily I had a backup of the configuration somewhere that wasn’t the Time Capsule and was able to restore them without a problem. You can restore the settings from:

AirPort Utility -> File -> Import Configuration File...

To take a backup of the configuration file:

AirPort Utility -> File -> Export Configuration File…

My backups on the Time Capsule are still in tact, I would have been very upset if I had lost them, but not devastated as I have an archive of the backups on there that’s about a month old, so I would have lost about a month’s worth of backups.


Posted in Hardware, Utilities | Tagged , , | Leave a comment

Thunderbird Backup Inefficiencies

Thunderbird stores all your e-mails in its profile directory. Each folder in Thunderbird is stored as a single file on disk. So all the e-mails in your Thunderbird Inbox are stored in a single file called ‘Inbox’ in your Thunderbird profile directory.

A problem arises if you are using Time Machine for backups. Then every time you receive a single 1kB e-mail in your Thunderbird Inbox, it will cause Time Machine to treat the entire Inbox file as changed and backup the whole file. I noticed the problem on a friend’s computer where their Inbox file was in excess of 700MB! As Time Machine uses a hard-linked directory structure, so every time the file changed 700MB was being taken up on the backup volume.

The problem is compounded by the fact that when you delete an e-mail from Thunderbird, it does not automatically reclaim the space taken up by that e-mail in the Inbox file. This means you are using backup space to back up e-mails that you don’t even want!

I’ve found a couple of ways to alleviate these problems. If you enable automatic folder compacting, it will reclaim the space used by deleted e-mails, when reclaiming this space would save at least the amount of space you specify, I have my limit set to 1MB and it seems to work well. However the limit applies to each individual folder, so if you have twenty folders there could be up to 20MB of deleted e-mails taking up space. You can get to the compacting settings through:

  • Thunderbird -> Preferences -> Advanced -> Network & Disk Space

Compact Folders Dialog

The second and more drastic measure you could take is to use Thunderbird’s archiving tool (Message -> Archive). This will store all of your e-mails from previous years in folders named by year e.g. ‘2010’, ‘2009’ etc. Since you are unlikely to get an e-mail date with a previous year, the contents of the archive folders will not change, and hence will not take up space with every backup. It has the added benefit of moving all old e-mails out of the current folders that do change frequently and making the backup overhead of these folders smaller.

It’s win-win with the possible exception that the archiving tool does not respect current folder structure, all e-mails from 2009 go into the ‘2009’ folder, regardless of which folder they were in before. This might annoy some people (myself included). You can manually archive and maintain folder structure, this would still bring all the benefits of archiving but it’s a bit more work. Since it’s only once per year I don’t see it as a great burden to maintain my folder structure in my archive.

Posted in Applications | Tagged , , , | Leave a comment

Time Capsule

I’ve been looking for a wireless access point that supports the wireless-n standard for a while. Both our MacBooks support wireless-n, but the access point from our ISP only supports wireless-g. While searching around for an access point I came across Apple’s Time Capsule. It’s a wireless-n access point, four port gigabit switch, router, NAS drive and wireless Time Machine backup node all rolled into one package.

I was sold on the Time Capsule and bought one from the Apple store. Everyone says it, but I feel it’s worth repeating – the retail experience at an Apple store is second to none. They have staff that know what they are on about and don’t mind spending time talking to you about their products.

Migrating my backups from our current server was not as straight forward as I would have liked. I instructed Time Machine to backup to the Time Capsule to force the creation of a machine specific sparse bundle on the Time Capsule – no need for a full backup. I then mounted the new sparse bundle and the existing backup sparse bundle in Finder. Then I used Disk Utility to ‘Restore’ the existing backup into the new backup. It took a while (overnight) and I had to unmount the new backup and the Time Capsule before Time Machine would recognise it, but I can now browse my old backups and my machines do incremental backups to the new Time Capsule.

There is a USB port on the Time Capsule so you can plug in printers, external drives and the like. If you plug in an external drive you can ‘Archive’ the Time Machine backups onto the external disk to keep an off-site backup. Given that Time Capsules only have one disk and previous generations have documented problems this is a good idea. Archiving took a long time (overnight again) but it feels good to have a copy of my backups off-site.

We use BT Infinity for our broadband service. This requires a Infinity modem which connects to a BT Home Hub over cat 5. The BT Home Hub is useless as a router, the configuration interface is clunky and you can’t do a lot of what you can with a Netgear equivalent. Luckily Jan has found out how to trick the Infinity modem into thinking the Time Capsule is a BT Home Hub. You can then use the Time Capsule as a router. Configuration is via Airport Utility and is both powerful and flexible. Not as many features as a Netgear equivalent, but all the ones that I typically use.

I’m very happy with it, the wireless doesn’t drop out and is really fast, making the internal disk the limiting factor when backing up, so I no longer need to connect an ethernet cable to get the best performance.

Posted in Applications, Hardware | Tagged , , , , | Leave a comment

Java2D Game – Whack Attack

I’ve been doing a lot of Java2D stuff at work recently, whilst I was doing it I had an idea for a game based on the mole whacking game at arcades of my youth.

The arcade game pops up moles, you have to hit them with with a club before they go back down. The more you hit, the better your score.

I thought this would would translate well to a desktop time passing game, and provide a good opportunity to sharpen my Java2D skills in the process. The latest development screenshot:

I’ve got ideas for more features such as a high-score server and different modes of gameplay. Check out where I’m up to at the moment by grabbing the latest development release:


Posted in Software Development | Tagged , , | Leave a comment

Going back in Time!

I was unfortunate enough that my new Mac had to be replaced – the USB ports developed a fault. Apple replaced it no quibbles, but didn’t copy my data onto the new Mac in the store.

I had a Time Machine backup so I didn’t think anything of it until I got home and then had to restore from it. This was more complex than I originally thought because my Time Machine backup is on an unsupported volume type the Migration Assistant didn’t find it (even with the unsupported volumes system setting turned on).

I rebooted with the OSX disc from the laptop box. Then mounted the Time Machine backup over AFP:

$ mkdir /Volumes/Backup
$ mount -t afp afp://<username>:<password>@<ip-address>/<backup-share-name> /Volumes/Backup

Then you have to force the volume to show up in finder:

$ disktool -l
.... Loads of output ....
$ disktool -m <volume_description>

Then under the ‘Utilities’ menu of the install disc there is an option ‘Restore from Backup…’. Select this then select the visible backup, it gives you a choice of which backups you would like to restore, and then to which hard disk to restore to. Select which ones you want and then click restore, mine took just under two hours.


Posted in Operating Systems, Utilities | Tagged , , | Leave a comment

Secure File Deletion

Sometimes there are files that you want to make sure are gone, not just removed from the file index, but physically removed from the disk so they cannot be recovered even if you knew where they were on the disk. Some innocent examples include bank statements, credit reports or plain-text versions of files you wish to keep encrypted.

On Linux I use an excellent utility called wipe. It’s brilliant for the information in its man page alone as well as the utility. There are options to specify how to go about wiping the files to be destroyed as well as advice on how this will affect the potential recoverability of the files.

In OSX there is a similar utility in the menu for the Trash can:

  • Finder → Secure Empty Trash…

It does not give options for how to go about destroying the files (as far as I can find) but seems to overwrite the file multiple times with what Apple claims is digital gibberish.

Posted in Operating Systems, Utilities | Tagged , , , | Leave a comment

MacBook Pro Missing Keys

I like the keyboard on my MacBook Pro. It’s well spaced and easy to type on, but it has a few limitations. One of the more inconvenient aspects is the lack of dedicated text navigation keys. I’ve found the following work in most places, but not all:

  • Home → Ctrl-a
  • End → Ctrl-e
  • Delete → I still haven’t found a shortcut for this!

I’ve also had trouble finding with a few symbols, notably the hash key which is used extensively as a comment character in system configuration files.

  • Hash (#) → Alt-3

If anyone has any better shortcut combinations or other common ones please let me know.

Posted in Hardware, Operating Systems | Tagged , | Leave a comment

Setting up Time Machine

I have been unfortunate enough to learn the hard way that a good backup strategy is an essential, not a nice-to-have. If you think this is melodramatic, imagine for a second that a disk died – right now – it choose this moment to give in. Where are all the photos? Not the low quality copy uploaded to Facebook, but the high resolution image that came off the camera? Where are all the important e-mails and documents? Without a working, tested backup system in place they all would have been lost.

So backups are great – but why incremental backup? Imagine a document, picture or other file that isn’t accessed very often became corrupt. With latest-copy backup system like rsync, or just copying the files to a server or external disk, there would be a backup of the corrupt file, which is of little use. With an incremental backup system it’s possible to recover a pre-corruption version from the backup. It’s also quicker than copying all the files over to another disk all the time because it only copies the changed files and only the bits of the file that have changed – if it’s not a naive implementation.

On my Linux box I was using rdiff-backup to keep incremental backups of all my stuff. OSX has Time Machine which does exactly the same thing, but with a cool interface that allows you to browse your backups and restore files using a familiar graphical environment. Unfortunately by default it does not allow backups to network volumes that aren’t provided by Apple. Whilst this is mildly annoying it isn’t difficult to change.

I currently backup to a server at home running Debian that provides an Apple Filing Protocol (AFP) service amongst others to our Macs, but it’s not natively supported by OSX for Time Machine backups! I have to credit the following web pages which were incredibly useful for getting Time Machine working for us:

Neither of the links worked on its own for me. I used a combination of them and the man pages shipped with OSX to get Time Machine to work, backing up to the server from our Macs. I used Matthias’ article to setup the server with AFP and Bonjour. After this I did the following on the Macs:

Firstly, just selecting the network volume to backup to in Time Machine and asking it to create a backup didn’t work for me. I had to create a backup sparse bundle first and copy it to the network drive where I wanted to keep the backup. To create the sparse bundle I used the command:

$ hdiutil create -library SPUD -size 1m -fs 'Journaled HFS+' \
  -type SPARSEBUNDLE -volname NAME_AABBCCDDEEFF.sparsebundle \

I replaced the text NAME with the name of the Mac that would be using the backup and the text AABBCCDDEEFF with the MAC (not Apple!) address of the ethernet port of the Mac that will use the backup. See the Mac OS X Hints article for more information.

This command is subtly different from the one in the Mac OS X Hints article. The command in the article didn’t work for me. I copied the sparse bundle to the network volume I wanted to keep the backup on. I haven’t tried putting it anywhere different, but I assume it must be in the root directory of the network volume.

In order for Time Machine to use this volume you must enable OSX to use unsupported volumes, another command:

# defaults write com.apple.systempreferences \
  TMShowUnsupportedNetworkVolumes 1

I made the mistake of not mounting the backup volume in Finder before configuring Time Machine. Unless the backup volume with the sparse bundle is mounted in Finder, Time Machine won’t allow you to select it as a backup location. I then configured Time Machine to use the backup volume. The first backup seemed to take forever and it was like it wasn’t using the full performance of the network, subsequent backups seem to flow much quicker over the network.

I excluded a few directories that I don’t want backed up, either because I don’t care about them or I only ever use them as a scratch pad and don’t intend for them to take up space on my backup volume. Notably Trash, Desktop and Music are never backed up – I either have copies elsewhere or don’t care about their contents.

That’s incremental backup working away in the background, keeping an up-to-date copy of all my data without me having to do anything. It offers the same functionality as rdiff-backup, but is much easier to setup and automatically makes a backup whenever it can connect to the backup volume.

Posted in Operating Systems, Utilities | Tagged , , , | Leave a comment

Firefox & Thunderbird Profiles

On my Linux box I use Thunderbird for handling all my email and Firefox is my default browser. Even if I don’t eventually remain using them I would like to copy their respective profiles across to my Mac so I can keep all my emails and bookmarks etc.

The default locations on Linux are in hidden folders ‘~/.mozilla/firefox’ and ‘~/.thunderbird’. I tired copying the profiles to the same location on my Mac but to no avail. A little bit of search using find on the command line showed up the default profiles in the following locations:

  • Firefox: ~/Library/Application Support/Firefox
  • Thunderbird: ~/Library/Thunderbird

The ‘profiles.ini’ files for the default profiles gave away their locations. I think it’s kinda cool that all the application configuration and data files that you don’t want to be hanging around your home directory have a place to live that doesn’t mean that are just hidden the your home directory.

My Firefox plugins seemed to work fine and with the exception of the a different theme it’s just the same as the Firefox for Linux. I’ve installed all the major browsers (Firefox, Safari, Chrome & Opera) and I’m currently test driving them to decide which to use. I like different things in all of them, if only I could pick and choose which bits I want from each I could make my ideal browser!

Thunderbird’s OpenPGP plugin is complaining that it can’t find gpg anywhere on the path. A friend recommended MacPorts which automatically downloads and builds the source for a lot of packages a bit like Gentoo’s Portage. I haven’t got around to installing it yet but it sounds like just the thing to sort it out.

Just like that, and my surfing and mail environments are ported from Linux to Mac with no real problems to speak of. Impressed.

Posted in Applications | Tagged , , , , , , | Leave a comment