Tuesday, 26 March 2013

HAPI 2.1 has been released (And HL7-over-HTTP update!)

After a much-too-long wait, HAPI 2.1 has been released. Once again, this relasse is packed with new features. Most importantly it begins a transition to a simplified API where everything is centered around a HapiContext that acts as a kind of "gateway" into the whole API, and a start down the road to eventually merging the powerful parts of the .protocol.* hierarchy with the easy to use .app.* hierarchy.

The API changes are non-breaking, so existing applications will work without modification, but we would encourage developers to migrate their code where possible to use the new APIs, since this will make code more readable. Information on how to migrate is found here.

As always, a complete changelog is available here. The website has also been enhanced with a new page outlining the Maven plugins available. This means that we finally have a good document explaning how one might generate their own custom message structure classes using Message Workbench (something we have been doing for years at UHN but have never documented).

The new release has been uploaded to Sourceforge, and has also had time to synchronize to the global Maven repos, so it should be fully available now. Thanks to everyone who contributed!

Update on HL7 over HTTP

In case anyone is wondering what is happening with this spec, I have a few updates of note.
  • First, the reference implementation has been completed and is available here (and through Maven). 
  • We have also begun production use of the spec with ConnectingGTA, a project UHN is leading which will ultimately link up about 700 organizations. So far we have had several people implement it using their own interface engines, and several people take advantage of the "relay" software that can be found on the HAPI website.
  • Most interestingly, the spec was submitted for consideration to the HL7 InM working group two weeks ago. It's still early days of course, but I am feeling hopeful that HL7 will consider adopting it officially.

And finally, a tech rant...

If anyone is curious why we announced in January that the release was imminent, but it took until late march to put it out, here are the gory details:

HAPI's message structures are built using the HL7 database, which is supplied as an Access DB file. The sourcegen module uses the Windows ODBC file bridge to read that database and generate its files. Because of this, we are dependent on Windows and the Microsoft ODBC bridge. Unfortunately that bridge is not supported on 64 bit Windows, so we have a Windows XP virtual machine that handles the builds.

The build started failing about a year ago with a strange IO failure during the compile phase ("Cannot read IN2.java: IOException: Invalid input parameter"). I worked around this during the last release cycle by generating the code on XP and then copying the files to OSX for compilation, but I really didn't want to establish this as the process since it's both tedious and risky (since it would be easy to miss files and release a structure JAR that was missing files).

Troubleshooting this issue ended up taking about 3 months, and in the end it appears to be (of all things) a bug in VirtualBox's "shared directory" implementation. Basically, if you have a file on your client OS with a size greater than a very specific number of bytes on a directory that is shared with the host OS using VirtualBox sharing, attempts to read the entire contents of the file using a java FileInputStream will fail. Ugh.

Anyhow... It's fixed.

What's Next?

Watch this space for a new release of the TestPanel over the next few weeks!


  1. Are you going to update this to HL7 V3?

  2. Your email address is bouncing from sourceforge.net

  3. Is there any way to find the examples as a maven project that can be imported into eclipse?