Downloads & Data

Download tools and source code; access data sources and services

Tar Balls

Download Now

Licensed under Apache License, Version 2.0

Jars

Download Now

Licensed under Apache License, Version 2.0

GitHub

Download Now

Licensed under Apache License, Version 2.0

Pseudonymisation Tools and Code

By Health & Social Care Information Centre | 10 April 2013

Using the apt repository

This is the preferred way, as it minimises the effort to use any of the other HDN provided code libraries. There are two steps:

  • Configure your system to use the apt repository
  • Make sure your system is up-to-date (Optional)
  • Install the packages

Configuring your system to use our apt repository

If you’ve configured your system to use the apt repository before you can skip this step.

  1. Open a terminal console (command prompt or command line) or ssh onto your chosen computer.
  2. Type curl -fsSkL http://services.developer-test.nhs.uk/repositories/hdn/hdn.sh | bash and press enter.
  3. Follow the prompts; where a password is requested, it is for the current user (you).
  4. Type apt-get update and press enter to update the system’s list of available packages.

Note: The repository is currently served over HTTP. It could be served over HTTPS, but there is not currently a certificate available for the server.

If you want to, you can as an alternative to the steps above you can download the entire repository using wget, and then set up it up locally by running hdn.sh file. Be aware that this will mean that you will not receive updates.

Make sure your system is up-to-date (Optional)

You can skip this if your system is up-to-date or you’re familiar with using apt and its finer points.

  1. Open a terminal console (command prompt or command line) or ssh onto your chosen computer.
  2. Type apt-get update and press enter to update the system’s list of available packages. (You can skip this step if you’re installing the apt repository for the first time using the instructions above).
  3. Make sure your distribution is current. Type apt-get –auto-remove –no-install-recommends –purge –yes dist-upgrade and press enter. You may receive prompts if your system is in an unstable state.

Installing the deb packages

  1. Open a terminal console (command prompt or command line) or ssh onto your chosen computer.
  2. Install the client. Type apt-get –auto-remove –no-install-recommends –purge –yes install hdn-pseudonymisation-client and press enter.

These steps will install the latest versions of these packages. If you need to install an older version, browse to http://services.developer-test.nhs.uk/repositories/hdn/precise/main/, find the version you want and then use apt-get pinning features to constrain the version. (For details, see the apt-get man pages).

Using the tar balls

This way is most suitable if you’re using a non Debian/Ubuntu based Linux (or one which is older than Ubuntu 12.04 LTS), a POSIX based system (eg Mac OS X) or cygwin. There are two steps:

  • Installing any necessary prerequisites
  • Downloading, decompressing and installing the tar ball

Installing Necessary Prerequisites

To use the tar balls, you’ll need to make sure the following are installed on your system and are available on the PATH of any terminal console you’ll be using:

  • bash (at least version 3.2)
  • tar (ideally the GNU variant; the BSD one has been known to cause trouble)
  • cURL (usually present as the curl binary; not present by default in cygwin)
  • Preferably one of gzip, bzip2 or XZ Utils (usually present as the xz binary), but these are not essential

Downloading, decompressing and installing the tar ball

Which tar ball you download and decompress depends on whether you have XZ Utils, bzip2 or gzip (or nothing at all). They all produce the same installation, but can reduce the size of the download substantially. The tar balls include a version number. You’ll need to know the version number of the tar ball you wish to download. The tar balls are named hdn-pseudonymisation-client_VERSION_all.tarEXT, where EXT is either xz, bz2, gz or `(blank).EXTidentifiers the way the tar ball has been compressed. In the instructions below,VERSION` refers to the version of the tar ball you are downloading. Versions are based on time stamps. If you’re not sure which one you want, the latest one is always stable. Browse to http://services.developer-test.nhs.uk/repositories/hdn/tarballs/ to see the possibilities.

If you have XZ Utils installed (it is present on all newer Linux distros)

  1. Open a terminal console (command prompt or command line) or ssh onto your chosen computer.
  2. Type curl -fsSkL http://services.developer-test.nhs.uk/repositories/hdn/tarballs/hdn-pseudonymisation-client_VERSION_all.tar.xz >hdn-pseudonymisation-client_VERSION_all.tar.xz where VERSION is substituted as above.
  3. Type sudo tar –extract –xz –numeric-owner –preserve –same-owner –no-overwrite-dir –verbose –file hdn-pseudonymisation-client_VERSION_all.tar.xz –directory /.
  4. Type rm hdn-pseudonymisation-client_VERSION_all.tar.xz.

If you have bzip2 installed

  1. Open a terminal console (command prompt or command line) or ssh onto your chosen computer.
  2. Type curl -fsSkL http://services.developer-test.nhs.uk/repositories/hdn/tarballs/hdn-pseudonymisation-client_VERSION_all.tar.bz2 >hdn-pseudonymisation-client_VERSION_all.tar.bz2 where VERSION is substituted as above.
  3. Type sudo tar –extract –bzip2 –numeric-owner –preserve –same-owner –no-overwrite-dir –verbose –file hdn-pseudonymisation-client_VERSION_all.tar.bz2 –directory /.
  4. Type rm hdn-pseudonymisation-client_VERSION_all.tar.bz2.

If you have gzip installed

  1. Open a terminal console (command prompt or command line) or ssh onto your chosen computer.
  2. Type curl -fsSkL http://services.developer-test.nhs.uk/repositories/hdn/tarballs/hdn-pseudonymisation-client_VERSION_all.tar.gz >hdn-pseudonymisation-client_VERSION_all.tar.gz where VERSION is substituted as above.
  3. Type sudo tar –extract –gzip –numeric-owner –preserve –same-owner –no-overwrite-dir –verbose –file hdn-pseudonymisation-client_VERSION_all.tar.gz –directory /.
  4. Type rm hdn-pseudonymisation-client_VERSION_all.tar.gz.

If you don’t have XZ Utils, Bzip2 or Gzip installed

  1. Open a terminal console (command prompt or command line) or ssh onto your chosen computer.
  2. Type curl –compressed -fsSkL http://services.developer-test.nhs.uk/repositories/hdn/precise/main/hdn-pseudonymisation-client_VERSION_all.tar >hdn-pseudonymisation-client_VERSION_all.tar where VERSION is substituted as above.
  3. Type sudo tar –extract –numeric-owner –preserve –same-owner –no-overwrite-dir –verbose –file hdn-pseudonymisation-client_VERSION_all.tar –directory /.
  4. Type rm hdn-pseudonymisation-client_VERSION_all.tar.

Using the standalone jars

The jars are listed under a version number (VERSION below). You’ll need to know the version number of the jar you wish to download. Browse to http://services.developer-test.nhs.uk/repositories/hdn/jars/ to see the possibilities. The jar you’ll need is called hdn-pseudonymisation-client.jar.

This jar is standalone. This means that it:

  • has a manifest so you can run as just java -jar FILE_NAME.jar
  • includes all dependent jars, including third party dependencies.

Once you have downloaded the standalone jar file you want, you can run it:

java -jar hdn-pseudonymisation-client.jar

If for some reason, you don’t want the embedded dependencies, you can download them without as hdn-pseudonymisation-client-without-third-party-dependencies.jar.

This is not to be recommended. If you don’t want the dependencies because you want to use the underlying libraries or source (or both), jump to the next section.

Using the Java libraries with source

The jars are listed under a version number (VERSION below). The sources are named the same as the jar, but with a .zip extension. You’ll need to know the version number of the jar and zip you wish to download. Browse to http://services.developer-test.nhs.uk/repositories/hdn/jars/ to see the possibilities.

These jar files are not standalone, but they do have a Class-Path annotation in their manifest which resolves to the other jar files they depend on. This includes a modicum of third-party dependencies (which, for the libraries, are a compile time dependency on annotations.jar, and for the executable clients, jopt-simple at runtime as well). The ‘Class-Path’ is set so that the dependencies are in the same folder.

The easiest thing to do is probably to wget all the jar files and sources for a particular version:

wget --no-parent --recursive 1 --no-directories --no-host-directories http://services.developer-test.nhs.uk/repositories/hdn/jars/VERSION/ FOLDER_TO_SAVE_IN/ && rm -r FOLDER_TO_SAVE_IN/index.html

Where VERSION is the version (above) and FOLDER_TO_SAVE_IN is a local path. You may want to make sure there’s nothing in FOLDER_TO_SAVE_IN before downloading. We recommend naming it after the VERSION.

Note: The source is designed to be compiled using Java 7, in particular javac, and has only been tested using OpenJDK 7. There shouldn’t be issues with other JDKs, but your mileage may vary. In particular, the Eclipse compiler has been known in the past to differ in its compilation of annotations.

Forking and Hacking on GitHub

It’s very hard to write superb libraries for others to use ‘in a vacuum’. The very best libraries are always extracted from real, working systems. (To some extent, this explains the exceedingly poor design of many java-supplied packages, such as collections, and the excellent third-party replacements (eg from Google)). A good counter to this is to see code as suitable to be forked, changed and shared for your projects. This is what we want with the HDN code. Without your efforts, and changes for your environments, we can’t improve things.

One can see the impact of the vacuum in this code. In many places, the Java code exposes fields as public final values. There are types which do no more than wrap strings. For those brought up used to ‘bean-style’ java programming, this might seem odd. However, it makes it far easier for you to find the place for your functionality, and add it. We can’t encapsulate properties and provide behaviours as methods as we don’t know your use cases – but we don’t want to commit to an anaemic domain full of getters and setters that do nothing but add noise. Indeed, we don’t want setters – we want you to use immutability, and constructor injection. Treat the arrays as immutable, and the collections, and it becomes simple to work with.

We’d encourage you to fork from github. The repository is at https://github.com/health-and-care-developer-network/health-and-care-developer-network. Take a look at Building to see how to get using it.