Browse and search developer information

Reference Implementation

ITK Java Reference Implementation

HSCIC ITK Java reference implementation of the ITK Java API. The purpose of the reference implementation is to provide a simple yet functional implementation of the ITK Java APIs for use as education and reference as well some potential real world usage in lightweight ITK compliant applications.

Design principles

Undoubtedly the ITK API and reference implementation could have been coded to be more elegant and more efficient. However in order to keep the code as general and simple as possible the following design principles have been adhered to:

  • Should adhere to the ITK specifications (version 2.01)
  • Should be as simple as possible
  • The API should hide the underlying transport specifics / complexity
  • Should be easy to integrate / extend with payload specific APIs – e.g. the CDAAPI
  • Have a consistent addressing scheme for all integration patterns
  • Only use core Java (i.e. avoid uncessary external dependencies)

Design Decisions

  • Servlet container required for inbound HTTP connections
  • Serialisation / deserialisation
    • Simple XML + XSLT used for message serialisation
    • XPath used to for deserialisation
    • Static helper methods provided on relevant classes
  • Asynchronicity of the Simple Asynchronous Pattern is managed at the application layer (note it would have been equally valid for this to be managed at the transport layer).
  • Message correlation is responsibility of application layer (not transport layers) – even for Infrastructure Acknowledgements
  • Simple message responses are created by the application layer
  • Whether or not to apply Base64 encoding is a property of the ITKService
  • Whether or not to add a distribution envelope is a property of the ITKTransportRoute (may be subject to change)

ITK Samples project

This is the HSCIC ITK samples project showing how the ITK API and reference implementation can be used to fulfill some common use-cases.

The best way to experiment with the ITK API and reference implementation is to download the samples and get them up an running on your own machine.

System requirements

  • Java: 1.6+
  • Web Browser: any relatively modern browser should do (it has been tested on IE8 & Chrome)


Download the itk-samples.war – this contains the API, reference implementation and some samples (in line with the scenarios).  If you would prefer to download the individual artefacts the complete list can be found on the downloads page.

Running the samples

The war is executable and can run independently of a web container.  To run it open a command prompt in the directory where the war was downloaded to and simply type the following command:

java -jar itk-samples.war

Your console should display something similar to this


Using your web browser navigate to and you should see a page showing all the samples.

To make sure everything is running correctly try the Get Patients By NHSNumber scenario – sending it to “local SMSP” (this points to – i.e. both the client and server end of the invocation are fulfilled by the samples project running on your local machine). If you get a response that looks like XML you are up and running – congratulations!

Deploying in an appserver

To deploy in an appserver just copy the itk-samples.war to the normal deployment folder for your particular appserver.

Invoking different endpoints

The samples project comes configured with multiple endpoints – in general these are:

  • Local <service-name> – A version of the service running on your local machine (i.e. by virtue of itk-samples.war)
  • <service-name> on Host B – Pre-confgured for execution of against the service running on a foreign host. This can be modified by aliasing hostb to point to a specific machine via your hosts file. Alternatively you can edit the file bundled in the war to point the HostB configuration to a known IP.
  • cloudharness – To get up an running with a remote service provider quickly we have configured some samples to run against the cloudharness service.
  • ITK Testbench – coming soon, configuration to work with a locally installed version of the ITK Testbench.


We would encourage you to make as full use of these resources as possible, however you do so at your own risk. The Apache license 2.0 states

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

Furthermore the following additional considerations should be taken into account:

  • These resources are primarily for education and are not intended to be used in a production environment.
  • These resources do not form part of the ITK specifications (they are non-normative). Where these resources conflict with the ITK specifications the ITK Specifications should take precedence.
  • This is not an ITK accredited product.
  • This is an initial (0.1) version of these resources and as such has not been subject to extensive scrutiny.